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Introduction 


This book is your guide to the Apple Il computer. This one book describes the 
Apple Il itself and covers the common peripheral devices and accessories includ- 
ing disk drives and printers. 

This book assumes you have access to an Apple ll system that is completely 
hooked up according to the instructions in the appropriate owner's manual pro- 
vided with each system component. It does not explain how to install your 
system, but rather how to use it once it is installed. 

What /s an Apple il? How do you make it work? The first two chapters of this 
book answer those questions. You have probably noticed that the Apple ll system 
is made up of several pieces of equipment all strung together with wires and 
cables. The first chapter tells you what all the pieces are and what they are good 
for. The second chapter tells you how to operate each component part. With this 
knowledge you are ready to use any of the ready-to-run programs that are widely 
available for word processing, financial analysis, bookkeeping, computer-aided 
instruction, and entertainment. | 

The next four chapters of the book teach you how to write your own BASIC 
programs on the Apple Il. Chapter 3 starts things off with a tutorial approach to 
the fundamentals of both versions of BASIC that are available on the Apple li, 
Integer BASIC and Applesoft. Chapter 4 continues with coverage of advanced 
programming topics and BASIC features. Two of the advanced topics, the disk 
drive and screen display graphics, are important enough to warrant their own 
chapters. Chapter 5 explains how to use the disk drive to store programs and data 
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files. Chapter 6 tells you how to program graphics on the display screen using 
both graphics modes available on the Apple ll. 

BASIC programs operate on the Apple Il under the supervision of the Apple Il 
Monitor. Chapter 7 explains both the standard Monitor and the Autostart Monitor 
from a BASIC programmer's point of view. The chapter also tells you how to 
incorporate an assembly language program into your BASIC program. 

Chapter 8 contains a complete description of each statement and function 
available in both versions of BASIC, including disk statements. Along with the 
appendices, it will serve as a handy reference once you know how to program in 
BASIC on the Apple Il. 


1 


Presenting the APPLE Il 


Figure 1-1 is a picture of a typical Apple ІІ computer system. Notice that it takes 
several separate pieces of equipment to make up a complete system. 

Your system may not look exactly like the one pictured in Figure 1-1. Many 
system components come from a long list of optional equipment. But there are 
three components that every system has in common: the Apple Il itself, the built- 
in keyboard, and a television. Let's take a closer look at each of these and at some 
of the more common pieces of optional equipment. We will not describe how to 
hook up any of these components to the Apple ІІ. For complete installation 
instructions, refer to the owner's manual supplied with each piece. 


KEYBOARD AND TV 


The keyboard and TV screen make communications with the Apple ІІ possible. A 
standard typewriter-style keyboard comes with the Apple Il. It transfers instruc- 
tions from your fingertips into the Apple Il. 

The display screen can either be an ordinary color television set or a color 
television monitor. А black-and-white TV works fine too, but of course color dis- 
plays will show up in black-and-white. The screen not only echoes everything you 
type so you can visually verify its accuracy, it also displays the reactions of the 
Apple il to your instructions. 

The standard display screen has three different modes of operation. One is for 
black-and-white text characters only and the other two are chiefly for graphics. In 
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FIGURE 1-1. A Typical Apple ІІ Computer System 


text mode, the standard screen is о 24 lines of 40 characters each. The 
graphics modes deal with points and lines, not characters, and subdivide the 
screen more finely (graphics are discussed further in Chapter 7). 

Most Apple Il owners use a television set for their display screen either because 

they have one or because it's a good excuse to get one. The television monitor 
produces a sharper picture than a TV set in the computer environment, but you 
can't use it to watch Sea Hunt, Highway Patrol, or the 6 o'clock News. Figure 1-2 
shows a typical television set hookup. 
--і> As you сап see, the TV does not connect directly to the Apple ІІ. A slide switch 
attaches to the TV antenna terminal. With the switch in one position, the TV is its 
normal erudite self; with the switch in the other position, the TV takes its orders 
from the Apple ІІ. A cable runs from the slide switch to a special small circuit 
board which fits conveniently inside the Apple Il. It is called an RF modulator and it 
converts the video signal from the Apple ІІ to something your television set can 
deal with. Your Apple dealer can sell you an RF modulator and show you how to 
hook it up. 

A television monitor requires no RF modulator; it attaches directly to the back 
of the Apple ІІ as shown in Figure 1-3. 


INSIDE THE APPLE Il 


The Apple Il itself houses the part of the computer that controls the rest of the 
system — under your guidance, of course! Lurking behind the keyboard are the 
main Apple ІІ memory banks, the microprocessor, the connection points for all the 
accessory components, and much more. Figure 1-4 discloses the true identity of 
these undercover items. 

The inside of your Apple ІІ may look a bit different from the one in Figure 1-4. 
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The basic layout will be the same — the large flat circuit board with dozens of 
small black integrated circuits (also called ICs or chips) in orderly rows and some 
small circuit boards mounted vertically in the s/ots at the back of the main circuit 
board. The number of chips and the number and placement of the vertical circuit 
boards varies from one system to the next. 


FIGURE 1-3. Television Monitor Hookup 
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FIGURE 1-4. Inside the Apple Il 


MEMORY 


Computer memory is typically measured in units called bytes. Each byte of 
memory can hold one character or a similar amount of data. Depending on the 
number of chips, your Apple ІІ computer has anywhere from 4,096 to 65,536 
bytes of memory. This is usually stated 4K to 64K, where K represents 1,024 
bytes. The amount of memory available determines how much the Apple Il can do, 
as we will see later. 

The Apple 1 actually has two kinds of memory. One is called read-only memory 
(ROM); its contents never change, even when you turn the power off. ROM con- 
tains the programs which give the Apple ll its unique identity and enable it to 
understand and respond appropriately to the commands you type in at the 
keyboard. The other kind of memory is called zead/write memory falso called ran- 
domsaccess.memory or RAM); its contents do change. n fact, Ihe. раша in 

"re | ory determines what task the Apple ll is 

Read/write memory works only as long as the power remains on. soon as 
you turn the Apple ІІ off, everything disappears from read/write memory. 
Ша ML ы ы а Ж ЖАДЫН ЫДЫ Қына oculi dd надай iic ori 


CASSETTE RECORDER 


Fortunately, you can use a cassette tape recorder to transfer programs to and 
from read/write memory, thereby storing a whole library of programs on cassette 
tape. Figure 1-5 shows a typical cassette recorder installation. 


һ 
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FIGURE 1-5. Cassette Recorder Hookup 


DISK DRIVE 


A disk drive far surpasses a cassette recorder as a program storage device. It is 
more reliable, stores more, and operates faster to boot. What's more, the disk 
drive easily and quickly stores data such as names and addresses for a mailing list, 
or correspondence for a word processor. Disk drives come in all shapes and sizes; 
different models have different storage capacities. Figure 1-6 shows two Disk II 
units (products of Apple Computer Inc.). 


PROGRAMS 


Let's take a slight detour from the guided tour of the Apple Il system and look at 
the different kinds of programs you will use with your system. We're not talking 
here about the different kinds of things you can do with your Apple Il, like word 
processing, accounting, financial analysis, and so forth, but rather about different 
classes of programs that must coexist in order for the Apple Il to perform any one 
of these chores. Programs that do things like play games, write letters, and so 


forth are called application programs, They always reside in read/write memory, 
not ROM. You transfer them to read/write memory froma cassette or disk. So 


whe u want sor, for insta u_use the 
| word nrocessing applicati i 
into read/write memory. Chapter 2 explains how to do this. 
More often than not, programmers write application programs in a program- 
ming language that is easy for them to use but which is too advanced for the 
Apple ІІ to understand without some help. A special program called an /nterpreter 
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FIGURE 1-6. Disk ІІ Hookup 


% 


does just what its name implies. It translates the application program from the 
language it's written in to a language the computer can understand. The Apple Il 
has a couple of different interpreters, which may exist in either read/write 
memory or ROM. 

The interpreter in turn relies on another program to coordinate the system 
components. This other program, often called the operating system program, per- 
forms fundamental system operations like transferring programs from cassette 
and disk to memory, and echoing keystrokes on the display screen. The Apple 1! 
operating system program is known as the Monitor. The Monitor always resides in 
ROM. Ep 


EXTERNAL DEVICE CONTROLLERS 


Notice the small vertical circuit boards which plug into the slots at the back of the 
main Apple Il circuit board. The slots exist to accommodate such special circuit 
boards. The circuit boards, called contro//ers.or cards, contain extra electronics 
which enable the Apple ll to use peripheral devices such as disk drives. 

Apple Computer Inc. makes a number of cards which plug into the slots in the 
back of the Apple ІІ. Some of them vie for the same slot, but most cards сап go 
into any slot. For the most part, the cards lack scars, birthmarks, or other dis- 
tinguishing features so it's hard for the uninitiated to tell one from the other. Each 
card is labeled with its name, but the printing is not always visible when the card is 
installed. You can usually identify a card from the slot it's in and what's connected 
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to it. As shown in Figure 1-6, the controller card for the Disk Il customarily inhabits 
slot 6; one or two disk drives attach to it. A second Disk T controller can go in slot 
5 for a third and fourth Disk Il drive, a third controller card can occupy slot 4 for 
drives 5 and 6, and so on. 

Let's take a look at some of the other cards you may have in your Apple 1! 
system. 

Each of the three cards shown in Figure 1-7 enhances the programming 
language capabilities of the Apple Il. There are two versions of the programming 
language BASIC available on the Apple Il: Integer BASIC and Applesoft. Installing 
the appropriate one of these three cards in slot O of your Apple Il makes it easier 
to switch from one version of BASIC to another. The Language System and 


Applesoft Firmware cards work on any kind of Apple Il, but the [nteger BAS/C card 
is.designed only f lus. The Language System card makes other 


programming languages, like Pascal і S well. 
The serial interface card (Figure 1-8) usually inhabits slot 1. Probably the most 


common device attached to it is a printer. 

It's not often that the parallel printer interface card (pictured in Figure 1-9) is 
used concurrently with the serial interface card, because it invariably has a printer 
attached to it. So the parallel printer interface card usually resides in slot 1. 

Figure 1-10 shows the communications interface card. With a modem con- 


с » 4 LS r 
necting the communications card to the telephone lin our Apple Il can get in 
touch with other computers at remote sites. Ix 

There are more cards available for innumerable tasks from sources other than 


Apple Computer Inc. For example, you can get cards to control lights and other 
electrical devices. Another card lets you write programs that electronically syn- 
thesize the sounds of musical instruments. There is even a card that works like an 
extension cord; it uses one slot in the Apple ІІ and provides several slots for addi- 
tional cards on a separate chassis. 


FIGURE 1-7. Left to right: Language System, Applesoft Firmware, 
and Integer BASIC Cards 
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FIGURE 1-8. Serial Interface Card 
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FIGURE 1-9. Parallel Printer Interface Сага 


Some Apple ІІ systems have a special card installed which allows twice as 
many characters on each display line as the normal Apple Il. In this case, the TV 
monitor (a TV set won't work) plugs into the special card instead of the main 
Apple ll circuit board. The special card plugs into one of the slots at the back of 
the main circuit board, usually slot 3 or 4. Figure 1-11 shows a typical card. 
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FIGURE 1-10. Communications Interface Card 
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FIGURE 1-11. Special Display Screen Setup 


GAME CONTROLS 


We will conclude the tour of the Apple Il innards with a look at the game controls 
which attach to the Apple 1! as shown in Figure 1-12. The game controls, or pad- 
dles, are used mostly by game programs but may show up in other places as well. 
Sometimes the game controls are not attached to the Apple ll at all. 
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FIGURE 1-12. Game Control Hookup 


PRINTER 


Let's turn now to the system printer (see Figure 1-13). 

Тһе printer joins the system via either the serial interface card or the parallel 
printer interface card (depending on what kind of printer itis), usually through slot 
1. There are printers of every size, price, and description. Some will print corres- 
^pondence that looks just as good as anything a typewriter can produce. Others 


will reproduce your graphics displays (in color, in some cases). Then there are 
those that are a compromise between the two. 


GRAPHICS TABLET 


The graphics tablet from Apple Computer Inc., pictured in Figure 1-14, is a handy 
device that exploits the graphics capabilities of the Apple Il in a special way. With 
its pen, you can create figures, cartoons, maps, charts, graphs, or any freehand 
drawing directly on the display screen, in color. Under your direction, it will draw 
straight lines, solid boxes, and dots. Your drawing can take up the whole screen or 
just part of it. You can move the drawing around, enlarge it, reduce it, and sepa- 
rate out its individual colors one by one. At any time during this procedure, you 
can save the screen image on the disk drive for later recall. You can even measure 
distances with the graphics tablet. 
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FIGURE 1-14. Graphics Tablet Hookup 
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How to Operate the Apple Il 


Any computer system can be a bit intimidating when you first sit down in front of 
it, even if it’s all hooked up, as your Apple ІІ system must be before you go апу 
further. This chapter will make you more comfortable around the Apple ll by ex- 
plaining how to use it, but it won't tell you how to set it up. The owner's manuals 
that come with each piece of equipment have complete instructions in them to 
help you with the installation procedure. If you need more assistance to be sure 
you've done it right, check with someone else who uses an Apple ll like yours, or 
with the dealer you bought it from. 


TURNING THE POWER ON 


Check that all the system components are connected together correctly and turn 
on the television set. Turn the volume all the way down. Locate the slide switch 
hanging from the TV antenna terminals and set it on the GAME or COMPUTER 
setting. Select the channel specified by the RF modulator instructions (usually 
channel 33). If you don't know which channel to use, ask someone else who uses 
the system or a dealer who sells the RF modulator. 

Locate the power switch on the rear of the Apple Il, next to where the power 
cord plugs into the computer. Turn the switch ON. You should hear a beep from 
inside the Apple Il. The beep tells you the Apple Il is ready. The POWER lamp on 
the keyboard will be on now unless it's burned out. 
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If you did not hear a beep, turn the switch OFF, then ON again. If you still do not 
hear anything, turn the power OFF. Was the POWER lamp lit? If it was not, unplug 
the Apple and plug in a lamp or a radio to see if the wall outlet has power. Read 
the instructions again and double check to make sure system components are 
hooked up properly. If the Apple still won't start, TURN THE POWER OFF! Unplug 
the Apple and get help from someone with more experience (your dealer). You 
can do a lot of harm by poking around the insides or switching connecting wires 
around. 


WHAT YOU SEE ON THE TV 


Once the power is on, and you hear the Apple ll beep indicating everything is all 
right, an image will appear on the TV screen. 

The exact image will depend on which variety of Apple ІІ you have, but one 
thing on the screen should be quite obvious because it will be blinking on and off 
at regular intervals. ТЫ j ite square is called the cursor. It marks the 
location where the next character you type will appear on the screen. The next 
section explains what to do if you don't see the cursor. 


If You Don't See the Cursor 


Your Apple ІІ тау have the Language System card installed along with one or 
more Disk |! drives. In this case, you won't see a cursor. Instead there will be some 
whirring and clacking noises coming from the Disk Il drive, and the red IN USE 
lamp on the front of the Disk Il cabinet will light up. For the time being, when this 
happens press the Reset key. The cursor will appear and the disk drive will quiet 
down. Go on to the next section. 

Some Apple ІІ systems аге set up to allow more than 40 characters on each 
display line. In order to see the cursor on such systems you must type a special 
command sequence like this: 


1. Press the Стаі key and hold it down, press the B key, and then release 
both keys. 

2. For the next command, you need to know which slot the special card 
(the one the TV monitor attaches to) uses, probably slot 3 or 4. You 
can open up your Apple ІІ and look inside — slots are numbered О 
through 7 from left to right. Figure 1-11 shows you what to look for. 
Get help from someone (your dealer) if you're not sure. 

3. If your TV monitor attaches to the card in slot 3, type PR#3 and press 
the Return key. If it attaches to slot 4, use PR#4; for slot 2 type PR#2, 
and so forth. 

4. The cursor will now be visible, although it may not be flashing (which 
is OK). Continue as described below. 
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TABLE 2-1. Prompt Characters 


* 


Monitor 
> Integer BASIC 


] Applesoft 


THE PROMPT CHARACTER 


To the left of the cursor there is another character. It is the first character on the 
line. It could be an asterisk (»), a greater-than symbol (>), or a right bracket (1). 
The Apple ІІ is a multilingual computer and the prompt character indicates which 
language it expects its instructions in. Table 2-1 shows the three prompt charac- 
ters and their corresponding languages. 


ж is the Monitor 


On many versions of the Apple 1! the first prompt you will see when you turn the 
power on is the ж prompt. If this is not the case on your Apple ll then you can skip 
this section and the next. 

The asterisk is the prompt for the Apple ІІ Assemb/y Language Monitor. 
Generally only advanced Apple ІІ users need to communicate directly with the 
Monitor. If you wish to experiment with the Monitor, you may do so now. While 
you can't do any harm by playing with the Monitor at this time, you will have to 
turn the power OFF and then ON again to undo the results of your experimenting. 

When the ж prompt appears, you must tell the Apple ІІ to switch over to 
BASIC. 


Crri-B into BASIC 


There is a Monitor command which instructs the Apple Il to switch to BASIC. To 
issue the command, press and hold the Ста. key while you press and release the В 
key. Then release the Стаі key and press the Return key. A different prompt will 
immediately appear underneath the ж. Depending on the kind of Apple ІІ you have 
and what options it has, you will either see the > prompt or the ] prompt. 
~A BASIC is.ana cronym for Beginner's All-purpose Symbolic Instruction Code, a 
widely used computer language that was developed at Dartmouth University. The 
—— 5» Apple Il supports two versions of BASIC: Integer BASIC and Applesoft. Both ver- 
sions contain enhancements to the original Dartmouth BASIC. 


> is Integer BASIC 


Тһе > prompt indicates that the Apple ll is ready for instructions in Integer BASIC. 
The rules for integer BASIC are different from those for Applesoft, but the two 
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have many things in common. For now we will stick to instructions that you can 
use in either version, so you need not worry about which BASIC you're using. 


] is Applesoft 


„Тһе ] prompt tells you the Apple Il is ready іп Applesoft. Don't worry for now 


which version of BASIC you're using. When it becomes a factor, we will talk about 
the differences between Integer BASIC and Applesoft. 


THE KEYBOARD 


The Apple ІІ keyboard (see Figure 2-1) looks much like the keyboard of an ordi- 
nary typewriter, but it has five keys you won't find on most typewriters. Two are 
on the left side, mysteriously marked Esc and Стя: . The other three are on the 
right, marked Reset, — and —. There are two more keys on the right side which 
you тау not recognize: Return and Верт. 

Go ahead and type on the keyboard. Nothing you can type can do any harm to 
the computer that can't be cured by turning the power off and on again. 

As you type, you may notice that all the letters displayed on the screen are 
capital letters, regardless of whether or not the Suirr key was pressed when you 
typed them. The standard Apple ІІ only knows how to display capital letters. You 
can attach your TV through a special controller which enables both upper and 
lower case. Also, some programs know how to display both upper- and lower- 
case letters. 


The Reset Key 


— t£ 

Reset is a very special key on the Apple ІІ keyboard. When Reser is pressed, every- 

thing stops. No matter what the Apple Il is doing when Reser is pressed, control of 
[mn al LEE 


K B] Ee] EE] E] e 
co'l WwW ГЕ к ү! ЕГЕ B е 


ES m] 5] ik] E] E ESI E.) 


&] Rd E E] ee 


FIGURE 2-1. Apple ІІ Keyboard 
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the Apple Il returns to the keyboard. Depending оп the Apple ll you are using, 
Reset will cause the Monitor, Integer BASIC, or Applesoft prompt to appear. 
Sometimes Reset can cause a lot of problems, especially if a Disk ll is in use 
when Невет is pressed. Therefore you must exercise extreme GOLES: о press 
the Reset key accidentally. Take care especially when you go after the Return key, 


as it is easy to get your finger a little too high up on the keyboard and hit the Reset 


key by mistake. Some versions of the le Il i is hazard by insist- 
ing you use Crat-Reset instead of just Reset (see the discussion of the Стаі key 
below). 
The Return Key 

ns 


As you type along, the characters you type show up on the display screen. In addi- 
tion, the Apple Il saves everything you type in its memory but does not try to 
interpret what you type as an instruction until you press the Return key. The 
Return key signals the Apple ІІ that you have finished the line you have been typ- 
ing. When you press Return, the Apple ll erases any stray characters that might 
be to the right of the cursor. Then it examines everything on the line that you just 
typed in. If those characters make up an instruction that the Apple ІІ can under- 
stand, it will take the appropriate action. Otherwise you will hear a beep and see 
one of these messages (or possibly some other message): 


"SYNTAX ERROR 
_ ЗНЗ SYNTAX ERR 


The Apple Il is letting you know that it did not understand what you meant by 
the characters you typed before you pressed Return . You must retype the line 
(without the error that tripped up the Apple 11). 


The SHIFT Key 


Letters are always upper-case on the standard Apple ІІ, so the Suirr key does not 
«даје between Tower-case and upper-case letiers. It does_allow some keys to, 
produce two different characters. You get one character by pressing a key 

the Suirr key held down and another by pressing the same key without holding 
the Suirr key down. The character you get with the бнт key is printed on the top 
edge of the key. 

We use the notation Suirt- to describe a double keystroke involving the Suirr 
key. For example, Suirr-3 produces the + character. 

Some letter keys do not display letters when they are typed with the Suirr key 
held down. The М key, for example, will display ^, and @ is displayed when you 
type a Suirr-P. Although the С key has the word BELL on it, Suirr-G does not dis- 
play a bell, just a G. 


The Ста. Key 
Стаі is a contraction of control. The Стаі key is always used together with 


another key in the same manner as the Suirr key. Y. е Сіңі, ke wn 
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while you press and release another key. This book designates the use of the Ста. 
key in conjunction with another key by prefixing the name of the other key with 
CrnL-. For example, CrnL.-B means press the Стаі and B keys simultaneously. 

The Crn. key, like the Suirr. key, allows some keys to have an additional func- 
tion. The G key is the only key labeled with its Cra. function: BELL. The meaning 
of BELL becomes obvious when you type CrnL.-G and the Apple Il responds with a 
beep. You are ringing the Apple II bell. 

The ther Ста. combinati ich cause various reactions from the 


dem We Lee covered the Monitor command CrnL.-B, which puts the App ple 
o Бапа, combination is Стаі -Х, Crri-X. It tells the Apple Il to disregard every- 


thing you've typed on the current t display lay line; you want to start over. Try typing 
something and then type CrRL-X. | he cursor zips back to the beginning of fhe line. 


Th ill appear on the display scre ple as no 
recollection of them whatever. As far as it's concerned, yo ype em. 


The EscKey 


Esc stands for escape, which is a term left over from the days when teletypes 
were common computer terminals. Somehow the name has stuck, even though 
pressing the key causes no breakout. The Esc key has a variety of uses, some of 
which come up in this chapter and the balance appear in the next chapter. 


Unlike the Sujet and CTRL keys, the Esc key is never used by holding it down 
Dad 
while pressing another key. Esc is and rele f t 
еу 15 pressed and released. This two-key operation is called an escape sequence, 
А simple escape sequence is Esc-@. You type this escape sequence by first 
pressing and releasing the Esc key, then pressing and holding the Suirr key while 
you press and release the P key (SHirt-P = @). The result? Everything on the 
screen is erased, and the cursor moves to the upper left corner. (In computer 
jargon, the upper left corner of the display screen is called home.) 


The — and — Keys 
Ln — 


The two arrow keys are called /eft-arrow and right-arrow. 

You will find the — and — keys very useful because they allow you to correct 
any typing mistakes you might make, and allow you to change information you 
have already entered. The — key works like the backspace key on a typewriter. 
Each time you press it, the character under the cursor is erased from the Apple Il 
memory and the cursor backs up one space. Try it right now. Type in any word 
(try PRINT). Press the — key several times and watch the cursor back up along the 
word you just typed in. Notice that the characters you back over do not disappear 
from the display screen. YOU CamTESTSEmUreT TNS ADI NSS DU TRE SUT eT its 
memory. Try backing the cursor all the way to the left edge of the screen. When 
yo d press the — again, the cursor jumps dow ine 
and a new prompt character appears. 
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As you might suspect, the — key meves-the cursor to the right along the dis- 


Pplay_line As the cursor moves forward along the line, every character it passes 
over gets copied into the A u ressed the 


key to generate that character. To see the — key in action, type in another word 
and back the cursor up a few spaces using the — key. Now press the — key a few 
times. Each time you press this key, the character the cursor passes over gets put 


back into the Apple ЇЇ memory exactly the same as if you had retyped it. ~ 
 _ _———-—-—:-:- —-—-—-.—---———- 


The Rept Key 
od лы n a 


Rept is short for repeat. If you hold the Rept key and any other key down at the 
same time, the other key will be repeated until you release one or both keysXThis 
is especially handy when the other key is an arrow key and you have a lot of 
characters to erase (— ) or recopy (—). 


Forthe repeat feature to work right, you must first hold down the key you wish 


repeated and then press the Rept key. Release Rept and the repeating stops. 
— ——— ee а алала ылан 


«X The Other Keys 2 P Ze. 


The other keys on the Apple ll keyboard are no doubt familiar to you. These аге о > 

the letters of the alphabet, the numbers zero through nine, and a standard set of Je 

symbols. e, 
Many typists do not distinguish between the number zero and the letter O or Та 

the number 1 and the lower-case letter |. The Apple ІІ can't cope with this Pre 

ambiguity. You must be very careful to type a numeral when you mean a numeral. 7r 

To help you remember, the Apple ІІ keyboard shows the zero with a slash through 

it, and zeros are displayed on the screen with that slash, too. 


THE CASSETTE RECORDER 


If your Apple system includes a cassette recorder, you can load programs from 
cassette tapes. Some program tapes come with the Apple ll, you can buy others, 
and you can make your own as well (we'll tell you how in Chapter 4). 


Handling Cassettes 


You should exercise care with the cassettes themselves. They are very easily 
damaged, and not easily replaced. 

Be very careful not to touch the surface of the tape in the cassette. No matter 
how clean your skin is, natural oils will contaminate the tape. Make sure you put 
tapes back in their cases when they are not being used. Never store them in hot 
areas, direct sunlight, or near magnetic fields (like those found near electric 
motors). 
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Write protect notches 


FIGURE 2-2. Cassette Write-Protect Notches 


Label Every Cassette 


You should label every cassette with information about the programs it contains. 
This avoids the headache of searching through cassette after cassette for the 
program you need. 


Write-Protecting Cassettes 


Each cassette has two notches in the rear edge. Most cassette recorders can 
sense the notches and will not record when they are present. Blank cassettes have 
tabs covering the notches so the tape may be recorded over. You can protect 
important programs by removing the correct tab and exposing the notch. 

To determine which tab is correct, hold the cassette so that the exposed tape 
is away from you and the side you wish to protect is facing up. Remove the tab on 
the right side to prevent recording over the side facing up (see Figure 2-2). Cover- 
ing a notch with adhesive tape will allow recording over a cassette that has been 
protected. 


Adjusting the Playback Volume 


You must set the volume control on your cassette recorder at the proper level for 
the Apple Il. If the volume is too low or too high, the information of the tape will be 
distorted and the Apple ll will not be able to understand it. 

The only way to determine what volume level is correct for your tape recorder 
is by trial and error. Here is the general procedure. First, try to load a program with 
the volume control set very low. If the low setting does not work, set the volume a 
little higher and try again. Keep adjusting the volume upward until you can suc- 
cessfully load the program. 
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You can use one of the tapes that come with the Apple Il. If the prompt 
character next to the flashing cursor is ], find the cassette labeled ''Color 
Demosoft." If the prompt is >, locate the tape labeled "Color Graphics." 

Insert the cassette into the recorder. Be sure that the program label faces up. 

For each position of the volume control: 


1. Rewind the tape completely. 

2. On the Apple ІІ keyboard, type the word LOAD. 

3. Depress the PLAY button on the cassette recorder to start the tape. 
4. Press the Return key. 


After you press Return the cursor will disappear. After 15 or 20 seconds you сап 
analyze your success. 

If you get the message ?SYNTAX ERROR or ***SYNTAX ERR, do not adjust 
the volume, just go back to Step 1 and try again. If this keeps happening, try 
cleaning the cassette recorder heads, or use a different tape. 

If nothing happens, or if ERR or ERRERR is displayed, press Reset, set the 
volume a little higher, and try again. 

If you hear a beep and no message appears, things are going well. The Apple 
has found the beginning of the program on the tape and is loading it. After about 
15 more seconds (depending on the length of the program on the tape), there will 
be another beep and the prompt and cursor will reappear on the screen. You can 
now stop the tape. Make a note of the volume setting so you don't have to repeat 
this procedure after using the recorder away from the Apple ll. 

When you see the BASIC prompt and cursor, the program has been suc- 
cessfully loaded. 


USING THE DISK II 


If you have one or more Disk ll drives connected to your Apple ll, you can get pro- 
grams on diskettes instead of cassettes The "System Master Diskette" supplied 
with the Disk ІІ has most of the programs Apple Computer Inc. provides on 
cassettes, plus a few extras specially designed for the ОРИ 


iskettes 
You must be very careful when you handle a diskette. Diskettes are much more 
delicate Tar-cassstte Tales Never band a diskette Never TOUChtre-wurtace-t ssette tapes, /Vever bend a diskette. Never touch the surface of 
the diskette (the part inside the oval shaped hole), and never force a diskette into 
the. Disk. Il drive. Always replace diskettes in their envelopes.when you remove 
them from the drive, and protect them from heat, direct sunlight, and magnetic 


fields (like those found near electric motors). Be especially careful with the 


"System Master Diskette.” 
nad 


22 APPLE Il USER'S GUIDE 


How to Insert Diskettes 
Info ihe Disk 11 Drive 


The proper way to insert a diskette into the Disk Il drive is shown in Figure 2-3. 

| Hold the diskette between your thumb and forefinger so that your thumb covers 
the label. Open the door on the Disk |! drive and gently slide the diskette all the 
way into the drive. There should be almost no resistance. If the diskette will not go 
in easily, remove it and try again. Make sure you are holding the diskette as level as 
possible. Once the diskette is inside the drive, gently close the drive door. The 
door should close very easily. If there is any resistance, release the door and push 
the diskette completely into the drive, then try again. If you force the door shut 
you will destroy the diskette. Sometimes it helps center the diskette if you wait to 
close the door until after the Disk ll starts spinning. 


2X THE DISK OPERATING SYSTEM 
| ed 


Before you can use any disk drive, a special program called Disk Operating 


be in mem rating Syste 


System must be in memory, The Disk Operating System, or DOS for short, js a 
special program which controls all the disk related activities. Ihe process.of.plac- 
ing a ey о in mem is call b y 


"bogt the ' or "boot the DOS" or just "boot DOS." 
You mm p DOS each time you turn the Apple Il off and back on again. 
n ———— '—— ИННИИ 


FIGURE 2-3. Inserting a Diskette into the Disk Il 
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FIGURE 2-4. Standard Disk Drive for Booting DOS 


,BOSURG DOS 
There are several different ways to boot DOS, depending on the configuration of 
your computer and the language being used to initiate the boot. Each method 
assumes the disk drive is plugged into slot number 6 and connected to the drive n 
terminal of the controller card. This is shown in Figure 2-4. 

Inse e System Master Diskette” into the correct drive and close the drive 
door. In some cases when the Language System is present, you must use a special 
diskette, the "Integer and Applesoft Il" diskette, before the DOS disk. This situa- 
tion is described below in the section on booting with the Language System. 


After a successful boot using one of the methods described below, the screen 
should look like one of those shown in Figure 2-5. 


Autostart Booting 
Lc — —— Ul 


The easiest way to boot the disk is autostart booting. As the name implies, boot- 
ing is automatic. In order for autostart booting to be possible your computer must 
have an Autostart Monitor. If, when you turn your Apple ll on, the Disk ІІ drive 
makes clicking and whirring sounds, and the red IN USE lamp on the front of the 
drive cabinet lights up, you have an Autostart Monitor. 

When the Autostart Monitor is present without the Language System, booting 
DOS is a one-step procedure. With the Apple Il power switched off, place the 
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FIGURE 2-5. Successful Boot of System Master Diskette 
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"System Master Diskette” in the proper Disk Il and close the drive door. Turn the 
power on. After a few seconds, the disk will stop and the screen will look like one 
of those in Figure 2-5. 


Booting from the Monitor 


When the * prompt character appears on the screen, the Assembly Language 
Monitor is waiting to accept commands. There are a couple of ways to boot the 
disk from the Monitor. 


Monitor Jump Booting 


You can boot DOS from drive 1 of slot 6 (see Figure 2-4) with the following Moni- 


tor command: 
+6000 


Remember to press Return. Тһе red IN USE lamp on the Disk Il will light up, and 
after a few seconds the screen will look like one in Figure 2-5. 


Стғі-Р Monitor Boot 


The other Monitor command you can use to boot the DOS is CrnL.-P. To boot from 
the Monitor using this command, type the slot number of the drive you wish to 
boot from (usually 6), then type Crn.-P (nothing will appear on the screen). Now 
press Return. After a few seconds the screen will look like one of those in Figure 
2-5. 


Bopti er BASIC 
or Applesoft 
we ee 


The same boot commands are recognized by both Integer BASIC and Applesoft. 

After the BASIC prompt character (> in Integer BASIC, or ] in Applesoft) type 
the letters IN or PR, then a pound sign (#), and then the slot number of the drive 
you wish to boot from (usually drive 6). The command should look like one of 


these: 
INS 


PR#6 


Now press the Return key. After a few seconds the screen will look like one of 
those in Figure 2-5. 


Booting with the 
Language System 


Under some conditions, booting DOS with the Language System present is a two- 
step procedure. The version of DOS being booted determines the procedure. 
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The version number of DOS on the “System Master Diskette” is stamped on the 
diskette label. It is a number like 3.3, 3.2.1, or 3.2. 

Booting version 3.3 of DOS is virtually the same with or without the Language 
System. Use the “System Master Diskette” with any one of the procedures de- 
scribed above. DOS is booted from the diskette into memory. Another step occurs 
automatically which makes both Integer BASIC and Applesoft available imme- 
diately, via the Language System. When the Disk Il stops, booting is finished, and 
the screen is similar to one of those in Figure 2-5. 

Booting DOS versions 3.2.1, 3.2, and lower requires two diskettes. First you 
must place the diskette labeled "Integer and Applesoft ll" in the correct Disk Il, 
usually the one connected to slot 6, drive 1. Then perform any of the boot pro- 
cedures described above. The drive will make sounds and the red IN USE lamp on 
the front of the drive cabinet will light up. In a few seconds, you will see this 
message on the display screen: 


INSERT BASIC DISK AND PRESS RETLIRN 


Now open the drive door and remove the diskette. Insert the “System Master 
Diskette” in the drive and close the door. Press the Return key on the keyboard. 
After a few more seconds, the screen will look like one of those in Figure 2-5. 
DOS is now successfully booted. 


How to See the Diskette Catalog 


If you have successfully booted the "System Master Diskette," you may be 
interested in knowing what programs that diskette contains. On the Apple Il 
keyboard, type: 


CATALOG 


The screen display should look something like the one shown below. (Did you 
remember to press the Return key?) 


DISK VOLUME 254 


*1 002 HELLO 

«1 083 APFLE-TREK 
*I O18 ANIMALS 

+В 009 UPDATE 3.2.1 
*1 014 COPY 

*I OOF COLOR DEMO 
+1 OS3 BRICK OUT 

«1 O24 SPACE WAR 

+I OSO THE INFINITE NO. OF MONKEYS 
#7 OS1 COLOR SKETCH 
#7 O83 SUPERMATH 

4I 024 AFPPLEVISIOCN 
#I 017 BIORHYTHM 

ФІ O27 PINBALL 
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REM INITIALIZED ON date 


REM SYSTEM MEMORY bytes 


REM DOS VERSION number 
PRINT “disk name” 
END 


FIGURE 2-6. Model Greeting Program 


Booting Other Diskettes 
Lon 


Wei lained how from the “System Master Diskette.” The pro- 
cedure is exactly the sam | been set и isk Il. 


Diskettes set up for other computers or other kinds of disk drives usually will not 
work in the Disk Il drive. "але 
M Me e» 


sy PREPARING BLANK DISKETTES 


From time to time you may need extra diskettes for the programs you run on your 
Apple Il. Before you can use a diskette with the Disk II for the first time, you must 
initialize it. If the application program you are using includes specific instructions 
for initializing diskettes, by all means use them. In their absence, you can use the 
following general instructions for preparing extra diskettes. 

The initialization process gets a diskette ready for subsequent use. During 
initialization, whatever BASIC program is currently in the Apple Il memory is saved 
on the diskette and becomes that diskette’s greeting program. The greeting pro- 
gram is automatically loaded and run whenever you boot the diskette. If you have 
a greeting program in mind, fine. If not, you can use Figure 2-6 as a model. Use 
t rogram exactly as shown except wherever there are italics, replace the 


ith actual information. The date is the date on which you initialize the diskette. 

The bytes are the number of bytes in the system memory (32K, 36K, etc.). The 
numberis the version number of DOS that is present on the diskette most recently 
booted (something like 3.2, 3.2.1, or 3.3). The diskette name is any name you 
want to use for that diskette. Illustrated below is an actual example of the 
initialization program: 

NEW 

10 REM INITIALIZED ON 1/1/21 

20 REM SYSTEM MEMORY 48K 

ЗО REM DOS VERSION 2.2.1 

40 PRINT "MISC., VOL. З" 

50 END 
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So to initialize a diskette, first prepare the greeting program, put the diskette in 
the drive, and type the following command: 


INIT HELLO 
Make sure the drive door is shut, and press Return. The red lamp on the drive 


lights up, accompanied by the usual whirrimg-amd-ctlckImg-sounds- The entire 
initialization process takes about two minutes, so be patient. en the lamp goes 


out, initialization is complete. 


Now. prepare.a label for the new diskette. Remove the diskette from the drive 
apply the label. 


LOADING AND RUNNING 
A PROGRAM 


There are many programs already written for the Apple ІІ. Some come on 
cassette, some on disk, and some on both. Some programs are written in Integer 


BASIC while others use Applesoft* Generally speaking, anA m will 
not work with the Integer BASIC prompt, and Integer BASI ms will not 
work with the A rompt. 
USE THE RIGHT VERSION OF BASIC 

While most versions of the Apple ll have both kinds of BASIC, not all do. The 
—J» Apple Il not have Integer BASIC unless the Language ystem card or 


Integer BASIC card is present. On the other hand, Applesoft is not available on 
many versions of the Apple I| until you load its interpreter from cassette or disk. 


If your Apple ІІ system has the Language System or the Applesoft Firmware 


card, it will automatically use the right version of BASIC for any application pro- 
gram you Toad, Otherwise, you must be sure the correct prompt character is in 
effect when you load a program from cassette or disk. 

On a standard Apple Il it is easy to get the Integer BASIC prompt (>). Press the 
RESET кө. and then type С-В lamemberia end Еа and then type Crat-B (remember to end with Return). 

It is harder to get the Applesoft prompt (1) on a standard Apple II since it 
resides on either cassette or disk. You must instruct the Apple Il to load the 
Applesoft interpreter into its memory from the disk or cassette. 

Before you can use the disk drive you must boot DOS as described earlier in 
this chapter. Once DOS is booted, you can load the Applesoft interpreter by plac- 
ing the System Master Diskette in the Disk Il and typing the following command: 

FF 
The drive will click and whir for a few seconds and then the Applesoft prompt 
character (]) will appear on the display screen. 

You can also get the Applesoft interpreter from cassette tape. Use the cassette 
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labeled ‘‘Applesoft Il" (from Apple Computer Inc.). Put it in the recorder and 
rewind it all the way. Type the command: 

Loar 

— 

Before you press Return, depress the PLAY button to start the tape. Soon you 
will hear the Apple ІІ beep, which means it has started to load the Applesoft 
interpreter. It takes about one and one-half or two minutes to load the Applesoft 
interpreter from a cassette tape. Once it is loaded, you will hear a second beep. 
Stop the cassette recorder. The Applesoft prompt will be on the display screen. 

From Applesoft, you can switch to Integer BASIC by typing the command: 

INT 


= 
If you then wish to switch back to Applesoft, you must reload the Applesoft 
interpreter from disk or cassette. 


> 


GRAM 
FROM CASSETTE 
a 


With the proper version of BASIC selected (or your Apple ІІ able to make the 
selection automatically), these are the steps for loading a program from cassette: 


1. Position the tape to the start of the program. This will usually be the 
beginning of the tape, in which case you must rewind the tape 
completely. If the program you want is not the first program on a 
cassette tape, you must load in turn each program that precedes it on 
the tape. Repeat the following steps for each extra program you must 
pass over. 

2. On the Apple Il keyboard type the command: 

LOAR 
3. Depress the PLAY button on the cassette recorder to start the tape. 
4. Press the Ветиям key. 


After you press Return, the cursor will disappear. After a few seconds, the 
Apple II will beep to signal that it has started to load the program. Some time later 
it will beep again signaling that it has finished loading the program. Use the STOP 
button on the cassette recorder to stop the tape. 

The program is now loaded. If you hear no beeps or if you get any error 
messages during the load process, recheck the volume control adjustments 
according to the directions given earlier in this chapter. If you still have problems, 
the cassette tape you are using has probably gone bad and you will have to re- 
place it. 


LOADING A PROGRAM FROM DISK 
——— ?Á—MCIOBN d 


Once DOS is booted, you can load a program from a disk with a command like 
——————————————————— ақына 


this: 
— LOAD program name 
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In actual use, program name is the name of the program to load. Naturally, a pro- 
gram by that name must be present on the disk that is in the drive. 


STARTING A PROGRAM RUNNING 
—  — À— H— ÁO (— 


When the program you want is loaded, use the following command to get it 
started: 
RLIN 


e е? 
es 


The program takes over control of the Apple 1, including the keyboard end dis- 
play screen. То regain control, you can type Crrat-C in most programs. You may 
have to press RETURN as well. If this does Not work, check the specific operating 
instructions for the program you are using. In a dire emergency, you can press the 
Reset key or turn the Apple ІІ power off and back on again, but in either case you 
may lose the program. 


SETTING TV COLOR 
n NN 


The Apple Il features full color graphics. If any of the programs you plan to use or 
write will use this feature, you should adjust the color settings on your television 
set or TV monitor for the correct balance. Apple Computer Inc. provides a pro- 
gram to assist in this task. With the Integer BASIC prompt (>), use the ''Color 
Graphics" cassette tape. With the Applesoft prompt (1), use the “Color 
Demosoft'" cassette tape or the COLOR DEMOSOFT program on diskette. In 
either case, load and run the program according to the instructions given earlier in 
this chapter. 

The screen will look like the one shown in Figure 2-7. 

What you see in Figure 2-7 is called a menu. A menu lists several choices (in 
this case, four) and asks you to choose one. To set the TV color, select number 
one by pressing the 1 key and then the Return key. Now the screen will show 16 
vertical stripes of color like the photograph in Figure 2-8, except in color. 

As you see, the colors are named along the bottom of the screen. From left to 
right, the colors are: 


BLAK Black BROWN Brown 
MGTA Magenta ORNG Orange 
DBLU Dark Blue GREY Grey 

PURP Purple PINK Pink 

DGRN Dark Green LGRN Light Green 
GREY Grey YELO Yellow 
MBLU Medium Blue AQUA Aqua 

LBLU Light Blue WITE White 


Now adjust the contrast, brightness, color, and tint controls on the TV until you 
get acceptable colors that agree with their names. Pay particular attention to pur- 
ple, pink, yellow, and the three blue colors. 

When you have finished adjusting the color, press the Return key and the 
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APPLE DEMONSTRATIQN PROGRAMS 


TE A C 
TO Poem. 


ar ne RIGHT. EDGE 
Wc 
DEMONS ATION. 


STANDARD COLOR NAMES 
STANDARD COLOR NUMBERS. 
KALEIDOSCOPE 
SKETCHING SCREEN 


WHICH WOULD YOU LIKE? 


© HITACHI 


FIGURE 2-7. COLOR DEMOSOFT Program Menu 
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FIGURE 2-8. Adjusting TV Color 


32 APPLE Il USER'S GUIDE 


menu reappears. You can choose any item on the menu if you wish to experiment 
a bit. To end the program, type Crrat-C (you'll have to end with the Return key). 


MISCELLANEOUS COMPONENTS 


This concludes the specific operating instructions for system components. For 
other components in your system, use the operating manual for that component. 
If you have a printer, for example, then you must refer to the printer manual, since 
operating instructions for printers vary widely from one brand to another. 


COPING WITH ERRORS 


The Apple Il is a marvelous piece of equipment but it shares a problem common to 
all computer systems. It lacks imagination. Every instruction you give must be 
exactly right or it will not work as you expected. The results of a mistake can run 
the gamut from annoying to aggravating to devastating. 


ERROR MESSAGES 


When you type something in wrong and press Return, the Apple ІІ usually re- 
sponds with a beep and a somewhat cryptic error message. Often the message 
gives you a clue as to what you did wrong; then again it may not. The general 
remedy is the same in either case: retype the line. You will find a complete list of 


error messages in Appendix C. 


CORRECTING TYPING MISTAKES 


As you type on the Apple ІІ keyboard you're bound to make mistakes. Some of the 
keys we described earlier make it easy to correct errors you notice on a line before 
you press Return to end the line. They are the —, —, Rept, CrnL.-X, and Esc- à keys 
and key sequences. 


* The — key backspaces the cursor and erases characters it passes 
over. Characters are erased from the program line even though they 
still appear on the display screen. 

* The — key moves the cursor forward, copying over (retyping) 
characters it passes over. 

* The Rept key, used in conjunction with the — and — keys, enables 
fast-backspacing and fast-forwarding. 

* The CrRL-X command cancels the line you're currently typing. 

* The Esc-@ command clears the display screen and leaves the cursor 
in the upper left corner. 


Chapter 2: HOW TO OPERATE THE APPLE 11 33 


Let's see how you might use these editing features. Suppose you want to type 
TS LOAD COLOR DEMOSOFT 
but instead you get this far and notice you've made an error: 
LOAS COLOR DEMOSCOFT 


You have two choices. You can type Crri-X to cancel the line and start all over 
again or you can use the — key to back up and correct the mistake. Press and hold 
the — key. Then press the Верт key. The cursor races back to the start of the line. 
Take your finger off the Верт key when the cursor gets to the first error. Remem- 
ber that as it backs up, the cursor is wiping every character it passes from the 
computer memory. If you back too far, use the — to line the cursor up over the 
offending S. Now press the D key, and presto! The line reads correctly. Do you 
know what will happen if you press Return right now? 


LOAD COLOR DEMOSOFT 
All the characters to the right of the cursor will vanish. 
LOAL 


That's not right! Before you press Return, you must move the cursor to the end 
of the line. You could retype the rest of the line, but you might make another 
mistake. The — key (together with the Reet key) moves the cursor to the end of 
the line, automatically retyping the characters it passes. 


K ACCIDENTAL RESET 


Sooner or later you will hit the Reset key when you did not intend to. It is inevita- 
ble, unless your Apple ІІ requires you to type Crat-Resert instead of just plain Reser. 
You can reduce the hazard by carefully prying off the plastic keytop, leaving just 
the keyswitch shaft available (Figure 2-9). 

You can take this one step further and make it physically harder to push down 
the Reset key. Get a small rubber washer about 3/8 inches inner diameter, 1/2 
inch outer diameter, and 1/8 inch thick. Remove the Reset keytop as shown in 
Figure 2-9. Work the washer over the exposed square flange of the keyshaft as 
shown in Figure 2-10. Replace the keytop. 


Recovering from Reset 


What you can do about an accidental Reset depends on what you were doing at 
the time the Reset occurred, and what kind of Apple Il you have. 

Any program you use on the Apple ІІ should have specific instructions about 
what to do if you accidentally press the Reset key while running that program. Be 
sure you know what to do before you start your program. If you press Reset while 
running a BASIC program you will be able to restart the program from the begin- 
ning. This is small consolation during some phases of accounting applications and 
the like, since rerunning could foul things up. 
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FIGURE 2-10. Guarding Against Accidental RESET: Phase II 
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When you press Reset, the Apple ІІ stops everything it was doing. Control 
returns to the keyboard; you will see a prompt character and the flashing cursor 
on the bottom of the display screen. If the prompt is a BASIC prompt then you can 
restart any program you were running by typing the RUN command. Some of 
what you did with the program since the last RUN command will probably be lost. 

If you see a Monitor prompt character (ж) after pressing Reset then you сап 
switch back to BASIC by typing Стві-С unless you were using cassette-based or 
disk-based Applesoft. To switch from the Monitor to disk-based Applesoft, type 
the following Monitor command: 


x3nDo 


To switch from the Monitor to cassette-based Applesoft, type the following 
Monitor command: 


aon 
(ештен so sure you use the correct command. If you are not sure which to 
use, ask sómeone who is. Use the wrong command and you are dead. You will 


have to reload your program, Applesoft, and possibly even DOS. 


3 


Programming in BASIC 


This chapter teaches you how to start writing your own BASIC programs on the 
Apple Il. 

BASIC is a programming language. Like any programming language, it consists 
of a set of statements, which you combine to create programs. А program defines 
the task you want the computer to perform. 

We could teach you BASIC by forcing you first to learn BASIC statements, one 
by one. But you would probably give up, since individual statements are not very 
meaningful. A study of individual BASIC statements quickly degenerates into 
learning a bunch of arbitrary rules that tell you nothing about programming or 
good programming practice. Therefore rigorous definitions of all BASIC state- 
ments have been relegated to Chapter 8. Look up individual statements in Chapter 
8 when you need to, but do not try to read Chapter 8 before you read this chapter. 


STARTING UP BASIC 


There are two different versions of BASIC available on the Apple Il. Some models 
of the Apple Il have Integer BASIC, some have Applesoft, and many have both. 
For now, you don't need to worry about whether you are using Integer BASIC or 
Applesoft. Later, when the difference becomes significant, we will discuss it in 
more detail. 
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Start with a BASIC Prompt Character 
Ne M a 


The Apple ll is a multilingual computer. If you wish to program it in BASIC, it must 
be expecting instructions in that language. You will find complete instructions for 
starting up BASIC in Chapter 2. Let's quickly review. 

=f Оп ап Apple ll with the Autostart Monitor, you need only turn the machine on 

| and press Reset (Crn.-Reser on some versions of the Apple ІІ keyboard). 

If your Apple ІІ does not have the Autostart Monitor, turn it on and press Crat- 

B, then Return. 

—A The prompt character in the left margin, next to the cursor, tells you which 
BASIC you are in. You have Integer BASIC if the prompt is a “>”. The prompt 7” 
means you have Applesoft. 


IMMEDIATE AND PROGRAMMED MODES 


Before we start worrying about how to switch the Apple ll between Integer BASIC 
and Applesoft, let's take a look at some simple BASIC statements you can use in 
either version of BASIC. Some of the examples in this chapter use the Integer 
BASIC prompt (>>) while others use the Applesoft prompt (1). You can try the 
examples in either version of BASIC, no matter which prompt you see in the book, 
unless specifically stated otherwise. Those examples with neither prompt can be 
used in either version of BASIC. 


PRINTING CHARACTERS 


When you first put the Apple ІІ in BASIC, it is in. / nedi alled 
direct or calculator mode. In this mode, the computer responds immediately to 


amy-inetruetions. you issue it. Try typing in this example: 
PRINT "LET SLEEPING DOGS LIE" 


Don't forget to press the Return key after the last quotation mark. The Apple Il 
prints the following message: 


LET SLEEPING DüGS LIE 


If the Apple ІІ prints the message ?SYNTAX E xx it is 
telling you your command was indecipherable. You probably misspelled the word 
| PRINT. If the Apple I! just prints the number 6 instead of any message. it means 
you left out the first quotation mark. In either case, you can just type the instruc- 
tion in again, but be more careful this time! Computers are extremely particular 
about spelling and punctuation. Even the slightest error can cause the computer to 
balk or — even worse — to do the wrong thing. 
A command like the one above instructs the computer to print everything be- 
tween the quotation marks onto the display screen. 
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here is а imit io-the-length. of the message you con put between quotation 
marks. The limit is different for Integer BASIC and Applesoft, but in both Cases it 
exceeds the width of the display screen. This means a command сап occupy 
mare than one display line. Long. commands like this automatically wrap around 


to the next lower line on the display screen. Try this command: 


PRINT “UNDER NORMAL CIRCUMSTANCES, THE М 
AN WOULD ВЕ CONSIDERED CRAZY" 

WINDER NORMAL CIRCUMSTANCES, THE MAN МО 
0 BE CONSIDERED CRAZY 


Integer BASIC allows about 120 characters. If you exceed the limit. you will get 
the message *** TOO LONG ERR after you press Return. 
а а л саа AS you approach ihe limit, the Apple Il starts 
beeping. When you exceed the limit, it prints а backslash (\) and automatically 


cancels your entry, as if you had pressed Crn.-X. 
——M—————————— 


PRINTING CALCULATIONS 


You can use the Apple ІІ in immedi de as you would а calculator; it responds 
directly with the answers to arithmetic calculations. Try these examples: 
——ү—Є;—үє—ү[үөүөүөү[ү————. + ——————_ 

PRINT 4+6 + Addition 

10 

PRINT 500-437 =- Subtraction 

оз 

PRINT 100ж23 Ж. Multiplication 

2300 

PRINT 96/12 ^l Division 

FRINT 3^2 А Exponentiation 

PRINT 33410-2300 Combination 

-630 


The correct answers are on the line immediately following each of the commands. 
Notice that you do not use quotation marks in these examples. Do you know what 
would happen if you did? Try it and see if you're not sure. 


Integer BASIC has a maximum and minimum limit on the value of a calculation. 
lithe value of a-celeulation is more than 777767 at any pott during The calcula- 
tion, the error message *** >327 RR appears. If the valugis less than 
-.32767, the message - *** >3 appears. 5ome examples of these 
errors are shown below. The last example shows division by O. 


SPRINT -32764-Z 
—### 022767 ERR 
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ЭРКІМТ 2°15-1 
sag 222747 ERR 
ЭРКІМТІ0О/О 

### 327567 ERR 


X Decimal fractions are not allowed in Integer BASIC. So, if you perform a divi- 
sion calculation that does not come out even, the remainder will be discarded. For 


example, try this calculation: 


SPRINT 9/2 
4 
“% Applesoft does allow fractions. Numeric values can have a total of nine s/gn/fi- 


cant digits including both fractional and nonfractional parts. This means that 
values with more than nine digits are rounded off to nine or r nonzero digits. 
These e es illustrate how this works: 


ІРКІМТ 12.2456789% Rounded Up 
12.342567? 


JPRINT 12.34567394 Rounded Down 
12.3456789 


If you try some of your own arithmetic calculations in immediate mode in 
Applesoft, you will notice the result is sometimes displayed using scientific nota- 


tion. 
JFRINT 122456789123 
1. 23456789E*11 қ. 
Emo 
If you do not understand scientific notation, stick to simple calculations for now. 
We will talk more about scientific notation and numeric values later in this 


chapter. 


Abbreviated PRINT Statement 
PŘ 


Applesoft allows you to abbreviate the PRINT statement with a question mark (?). 
pp ws you revi RIN with a questi rk (?) 


Here are some examples you can try: 


J?"TIME MARCHES ON" 
TIME MARCHES ON 


1213-46%6 


-262 


ERROR MESSAGES 


So far we have mentioned several messages the Apple ll will issue when it detects 
situations it cannot cope with. It beeps to draw your attention to the fact that 
something is wrong, and it tries to diagnose the problem for you. Its diagnostic 
abilities are limited, though, so do not expect a definitive analysis of your error. 
There are fewer than 35 possible messages the Apple ll can use to respond to the 
myriad of possible errors and combinations of errors. 
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Throughout this chapter and the rest of the book we will make note of some of 
the errors that can occur in specific situations, especially the insidious ones. All 
error messages are listed alphabetically in Appendix C. 


Error Message Format 
MA EIU eeu ee e 


Error messages have a slightly different format in Integer BASIC than in 
Applesoft, as shown below: 


JFRNIT "THE LAVA FLOWS" 


Ар b so. PONTA X ERROR 


PRNIT "THE LAVA FLOWS" 


Zonas { е SYNTAX ERR 


EXTRA BLANK SPACES 


Are you struggling with the question of where to put spaces in a line and where 
not to? Don't worry. The Apple ll interprets a BASIC line by the elements in it. 


Spaces, or blanks, are irrelevant. ce you must put spaces is within 
quotation marks, where you want spaces to be part of a message. 


STATEMENTS, LINES AND PROGRAMS 


A program consists of statements Il with an 
exact and complete definiti t hich it is to perform. If the task is short 
and simple, the program can be short and simple as well. The immediate mode 
instructions we have experimented with so far are each small, simple programs. 
Each one has just one statement — one instruction to the Apple ll. These аге triv- 
ial cases. Most programs have 10, 100, 1000, or even more statements. Consider 
the following statements: 


PRINT "COWS MOQO" 
спы5 Moo 


PRINT “FOR FANCY BLUE" 
FOR FANCY BLUE 


FRINT "НОСЕ ВМ" 
HOCOF —B-—NLI 


Each of these immediate mode programs prints a line of text on the display 
screen. Each program has exactly one statement and exactly one line. 


Applesoft allows you to put more than one statement ор a line. You separate 
multiple statements on the same line wi colon (:). Compare this immediate 
-— A————————————— oss 
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mode program with the example above: 


JPRINT "COWS МОС": РКІМТ "FOR FANCY BLUE" 
>PRINT"HOOF-B-NLU" 

COWS Moo 

FOR FANCY BLUE 

HOOF -B-NLI 


This three-statement, one-line program prints the same three lines of text as the 
previous three one-statement programs. 

There i ific limit to the number of ement lesoft pro- 

g i line cannot be longer than 255 characters, though. If 

ou are typing a long line, the computer will start beeping when you type the 

48th character to warn you you. are.approaching the limit. If you exceed the limit, 

omatically cancels the line, just as if you had typec BL-X апа you must 


start over. It does not perform апу of the instructions you typed on the too-long 
line. So there is a limi і -line.i j ode 


program. 


A One-Line Program in Applesoft 


You can put quite a lot of program on one line in immediate mode, thanks to 
Applesoft's ability to handle more than one statement per 255-character line. For 
example, consider the following statement: 


— Ó JFüR 1=1 TO 800: 7"A"s NEXT: ?"PHEMW! " 
| | „OPRINT - 
Ignoring the meaning of this “ппіпі-ргодгат” for now, type it in exactly as 


shown, ending with a Ветиям. If you type it in successfully, you will see the letter A 
displayed across the next 20 lines of the 40-column screen, followed by the 
message PHEW! on the 21st line. 


AAABRARAAAAARAAARAARARAAARAAAAAAAARAAAARAA 
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 
AAARAAAARARAARARAARARAAAARAARAAAAAAAAARA 
AR ARAAARAARAARARAAAAAARAAAAAAAARARARAAAA 
AARAAAARAARAARARARAARAAARRAAARAARAAAAARAA 
АЛАААЛААЛААЛАААЛАААЛАЛААЛАЛАЛАЛААЛААЛАЛАЛА 
AA ARAARARAAAARARAARAAAAAARAAAAAAAAARAAAA 
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 
ARARAAAARARAARARAARARARAAAARARAAARAAAARA 
AAR AARAAA AB ARAARARRAARAAARAAAAAAARARAARAA 
AARAARAARARAAARARAAAAARARRAARARARAAAAAAA 
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 
AAAAAAAAAAAAAAAAAAARAAAAAAAAAAAAAAAAAAAA 
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 
АЛААЛАЛААААААААААААААААААААААААЛААААААЛА 
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGAA 
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 
AANAAAAAAAAAAAAAARAAAAAAAAAAAAAAAAAAAAAA 
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 
FHEW! 
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The program line is conveniently left at the top of the screen. This is because 
the program displays just enough lines to scroll the program line to the top of the 
а 40-column screen, but not off it. 

When the one-line program described above is finished, the Applesoft prompt 
is displayed with the cursor adjacent to it on the bottom line of the display screen. 


PROGRAMMED MODE 


The programming we have done so far is educational and, hopefully, interesting, 
but there is only so much you can do in immediate mode. This is especially true in 
Integer BASIC, with its limit of one statement per program line. Another problem 
with immediate mode programs is that you have to retype the program each time 
cuss shortly that will allow you to reuse the program as long as it still appears on 
the display screen, but this is still a limitation. 

What you need is a way to enter several program lines and to hold off using 
those lines. That way you can write programs to do tasks that are too complex for 
one-line programs. 

There is a way to get around the problems of immediate mode, and that is to 
write programs in programmed mode, also called deferred or indirect mode. In 
programme ode, the computer accepts and stores the program in its memory, 
but does not perform any of the operations spec ou te 


it to do so. You can enter as many program lines as you want. T уу ou 
enter the appropriate co я uter performs the operations ifi 
by the programmed mode program. 


Program Execution 


We say the computer executes or runs a program when it performs the opera- 
tions which the program specifies. 


In immediate mode a program is executed as soon as you press the Return key. 
In programmed mode you must issue the command to execute a program. 
Each time you do so, the program runs all over again. —— ысымы 


Clearing Out Old Programs 
M co 


Because the Apple ІІ stores programmed mode programs іп its memory, you must 
specifically instruct it to erase an o ou type in a new program. 


Do this by typing the command NEW. If you forget to type NEW, your new pro- 
gram will be mixed in with your old program. 


Ending Programs Properly 


Ne 
he end of an immediate mode program is obvious. Not so with programmed 
mode, as we shall see. The END statement tells BASIC to stop executing your pro- 


L 
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gram and return to immediate mode. Therefore an END statement should be the 
last statement your program executes. 


—p ^ 


pplesoft does not require an END statement. It ends a program automatically 
when it runs out of instructions. 


Line Numbers 


Line numbers make programmed mode possible. A line number is simply a one, 
two, three, four, or five-digit number entered at the beginning of a program line. 
The line number is the only difference between a programmed mode program line 
and an immediate mode program line. There are some instructions that can be 
used only in immediate mode and others that can be used only in programmed 
mode; we will discuss them later. 
Try this sample programmed mode program: 

УМЕН 

210 FRINT "RUBBER BABY BUGGY BUMPERS" 

220 END 

УКИМ 

RUBBER BABY BUGGY BUMPERS 


Each line number must be unique. No two program lines can һауе the same 


number. If you use the same line number more than once, the computer only 
remembers the last program line you used it with. To see how this works, type in 
ИНТЕР rere 


these program lines: 
>МЕЫ 


>10 PRINT "FIRST LINE 10" 
210 PRINT "SECOND LINE 10" 
220 END 

>RLIN 

SECOND LINE 10 


Line numbers determine the sequence of program lines in a BASIC program. 
The first line must have the smallest line number, while the last line must have the 
largest line number. Even if you type in the lines out of order, the Apple 1 will inter- 
nally rearrange them in the proper sequence ine number. Consider this pro- 
gram, with line numbers out of order: 


ZNEW 


230 PRINT "CLIT" 
210 FRINT "FISH" 
2z0 PRINT “OR" 
>40 PRINT "BAIT" 
250 END 

УКиМ 

FISH 

ПК 

CUT 

BAIT 


Chapter 3: PROGRAMMING IN BASIC 45 


To prove that the Apple ІІ does not forget programmed mode in programs, 
clear the display screen with the Esc- 2 command and then rerun the program. 


> -—— Press Esc-@, then Return 


SRN 

FISH 

OR 

CLT 

BAIT 

It is a simple matter to add program lines to a program that is currently in the 

computer's memory. You can add a line to the beginning, the end, or anywhere in 
the middle of a program by typing the line with a line number that will position it 
where you want it. Suppose you wanted to add a line to the beginning of the last 
example program. As long as you have not typed the command NEW, the pro- 
gram will still be іп the Apple II's memory. Since the lowest line number currently 
in that program is 10, any program line you type in now with a line number less 
than 10 will be placed at the beginning of the program. Try this: 

>S PRINT "EITHER" 

DRLIN 

EITHER 

FISH 

OR 

CUT 

BAIT 

It's a good thing the original program started with line 10 rather than line O! It's 
always a good practice when assigning line numbers to start your program with a 
fairly high line number and leave plenty of room between line numbers so you can 
add program lines later on. 
lalan 


Multiple-Statement Program Lines Spare k b 4 С ) 


You can put more than one statement on a single program line. The first state- 
ment follows the line number. The second statement follows the first, with a 
colon (:) in between. Colons separate the statements on a multiple-statement line. 

Integer BASIC allows you to put more than one statement on a line in program 
mode, unlike immediate mode. Line length is limited to approximately 150 charac- 
ters. The exact line length limit varies depending on the content of the line. If you 
type a line that is too long, the Apple Il displays the error message ««« TOO LONG 
ERR and you must retype the line. 

Multiple-statement program lines are allowed in Applesoft in both programmed 
and immediate modes. In both cases, the line length limit is 255 characters, as we 
described earlier. 


Listing Program Lines 


You can see what program lines the computer has stored іп its memory at any 
time by typing the command LIST. Try it right now. If you have not type 
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since you tried the last example, you should see the following program lines dis- 
played on the screen: 


Г 
н 
її 
- 


a PRINT "ЕТТНЕК”" 
10 PRINT "FISH" 
20 PRINT "OR" 

30 PRINT "CLT" 
40 PRINT "BAIT" 
50 END 


This_is called a program listing . There are variations of the LIST command which 
allow you to list one line at a time or a group of lines. This latter option is especially 
handy when you have a long program that will not fit on the display Screen all at 
once. With the last example program still in the computer's memory, typing the 
command 
LIST 20 


causes the following program line to appear on the display screen: 
10. PRINT *FISH^" 


To list several sequential program lines, you must specify both the starting and 
éfiding line number, as in this example: 
LIST 20,40 
20 PRINT "OR" 
SO PRINT “CUT” 
40 PRINT "BAIT" 


Applesoft, you can list all program lines up to and i j ific pro- 
gram line. You can also list all program lines starting at a specific program line up 
to the end of the program. Here are examples of those two versions of the LIST 
кла” 

JLIST;10 
= PRINT "EITHER" 
10 PRINT "FISH" 


JLIST 30; 


ЗО PRINT "CUT" 
40 PRINT "BAIT" 
50 ЕМІ 
Interrupting a Listing 
listi fore it reaches the end by typing CTRL- is is especiall 


useful for aborting the interminable listing of a long program. 


our Apple ІІ has the Autostart Monitor, you can suspend, or temporarily 


freeze the listing of a program by typing Crat-S. The listing will resume when you 
SL ее... НЦ 
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press the space bar. Crat-S allows you to review the listing of a long program at 
нана 


your own pace: 


Automatic Line Numbering 


The Apple Il will automatically number your Integer BASIC program lines for you. 
Use the AUTO command to institute this. The computer will then supply the next 
line number each time you press the Return key. It will not advance to the next line 
number if it finds an error on the line you just finished, or if you entered nothing on 
the line except RETURN. 

To get out of the automatic line numbering mode, type CrnL.-X. This cancels 
the line number provide the computer. Following that, typ e command 


To see how the AUTO and MAN commands work, type in the following: 
>AUTO 1000 


21000 PRINT “HOW MANY YARDS IN A MILE?" 
21010 Just press RETURN 

21010 PRIMT 5220/3 

33434 SYNTAX ERR 

21010 PRINT 5250/3 

>1020 \  PressCra-X 

>MAN 


2 


As you can see from the example, AUTO requires you to specify which line 
number automatic line numbering should start with. You can also specify the 
increment between line numbers. The following example illustrates this option. 


TAUTO 1000,100 


21000 PRINT "FISH OR CUT BAIT" 
21100 \ 
>МАМ Press Crat-X 


In this example, line numbers are incremented Бу 100. If you do not specify the 
increment, the Apple ІІ defaults to 10 as in the previous example. 
Applesoft does not have the automatic line numbering feature. 


SAVING PROGRAMS ON CASSETTE 


A cassette recorder gives you the means of saving a programmed mode program 
outside the main computer and later loading that program back into memory. 
Suppose you have the following program in memory. 

10 PRINT "TOTO," 


20 PRINT "I" 
30 PRINT "DON’T" 
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40 PRINT "THINK" 

50 PRINT "WE^RE" 

&0 PRINT "IN" 

70 PRINT "KANSAS" 

80 PRINT "ANYMORE" 

90 END 
To save this program, put a tape in the cassette recorder. Rewind it to the begin- 
ning, then press the RECORD and PLAY buttons simultaneously on the cassette. 
recorder and enter the following command right away at the keyboard: 


SAVE 


The Apple ll will beep as it starts recording the program on the tape and will beep 
once again when it finishes. Press the STOP button on the recorder after the sec- 
ond beep. 

At this point type in NEW followed by LIST to erase the program from the com- 
puter memory and verify that it is gone. To load the program back into the com- 
puter from the tape, first rewind the tape to the beginning. Then press the PLAY 
button on the cassette recorder and enter the following command at the 
keyboard: LOAD 


The Apple ІІ beeps as it starts to load the program from the tape and beeps once 
again when it finishes. You must manually stop the tape after the second beep. 
Use the LIST command to verify that the program is in the computer memory. 

In Chapter 5 we will see how to save and load programs onto disk, which is 
even more convenient than cassette tape. 


Saving Multiple Programs 
on One Tape 


You may have noticed that it did not take very much tape to save the one pro- 
gram. А longer program would require more tape, but usually there is enough tape 
on one cassette to hold several BASIC programs. You can save programs sequen- 
tially on the tape: the second follows the first, the third follows the second, and so 
on. 

Loading the second, third, and subsequent programs on a cassette is not as 
straightforward as loading the first. After you rewind the tape to the beginning, 
you must get past the first program in order to load the second, past the second 
to get at the third, etc. You can do this by typing the LOAD command repeatedly 
until the program you want is in memory. This is a slow process, but it works. 

You can speed things up considerably if your cassette recorder has a tape 
counter. Reset the tape counter to O when you rewind the tape to the beginning 
before saving a program. After saving the first program, jot down the tape 
counter reading. This is the starting tape counter reading for the second program. 
Save the second program and note the tape counter reading at the end of it (for 
the start of the third program). 

Now to load the second program, rewind the tape to the beginning and reset 


h 
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the tape counter to O. Then use the FAST FORWARD button on the cassette 
recorder to position the tape counter to the reading for the start of the second 
program. You can use the REWIND button on the cassette recorder to back the 
tape up if you overshoot with the FAST FORWARD button. Now use the LOAD 
command to get the second program. 


SWITCHING BASICS 


On many versions of the Apple ІІ, you have a choi rogramming in 


Integer BASIC and Applesoft. The reasons for choosing one version of BASIC 
over the other will become apparent as you progress through this chapter. We 
have айке Тогоо tal ТЕ PATIO wil arovide Ooan ins num- 
bars automatically while Applesoft will not- On the other hand, Applesoft allow plesoft will not. On the other hand, Applesoft allows 
you to use numeric values with fractions, while Integer BASIC does not. 

ile most versions of the Apple ІІ have both versions of BASIC available, not 
all do. The standard Apple ІІ Plus has only Applesoft, for instance. The procedure 
for switching from one version of BASIC to the other varies depending on which 
model of Apple ІІ you have, and which options are installed on it. 

With the Apple Language System option, you have immediate access to either 
version of BASIC. If you are in Integer BASIC, type FP to transfer to Applesoft. 
Fro | er BASIC. 

The Applesoft firmware card also allows you immediate access to either ver- 
sion of BASIC. It has a switch which protrudes through a slot on the back of the 
Apple ІІ and determines the version of BASIC. You will get Integer BASIC if you 
turn on the Apple Il with the firmware card switch in the down position. When you 
turn the Apple ІІ on with the firmware card switch in the up position you get 
Applesoft. Regardless of the switch setting, you can type FP for Applesoft or INT 
for Integer BASIC if the firmware card is installed. 

On a standard Apple ll it is easy to get Integer BASIC. Press the Reset key, and 
then type CrnL.-B. It is harder to get Applesoft on a standard Apple ll since it 
resides on either cassette or disk. You must instruct the Apple ІІ to load Applesoft 
into its memory from the disk or cassette. 

Before you can use the disk drive you must boot the Disk Operating System 
(DOS) as described in Chapter 2. You must do this each time you turn the com- 
puter back on after it has been off. To review briefly, here are the standard 
instructions for booting DOS from the Monitor and Integer BASIC: 


%4. Press Crat-P, then Return 


PRES 


Once DOS is booted, you can put the Apple Il іп Applesoft from Integer BASIC 
by placing a disk with Applesoft on it in the disk drive and then typing FP. In a few 
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seconds the Applesoft prompt character (]) will appear on the display screen. 

You can also get Applesoft from cassette tape. The complete procedure for 
doing this is described in Chapter 2. Briefly, you must put the Applesoft cassette 
in the cassette recorder, press the PLAY button on the cassette recorder, and type 
the LOAD command from Integer BASIC. In 1-1/2 or 2 minutes, the Applesoft 
copyright notice and prompt character will appear on the display screen. 

From Applesoft, you can switch back to Integer BASIC by typing the command 
INT. If you then wish to switch back to Applesoft, use the FP command with the 
disk drive, or the LOAD command with the cassette tape. 


ADVANCED EDITING TECHNIQUES 


In Chapter 2 we looked at ways you could correct errors in a line you are typing 
before you press the Return key. Let's quickly review those simple editing tech- 
niques. 


The — key backspaces the cursor and erases characters it passes over. 
Characters are erased from the program line even though they still 
appear on the display screen. 

The — key moves the cursor forward, copying over (retyping) characters 

- — it passes over. 

The Нерт key, used in conjunction with the — and — keys, enables fast- 

ackspacing and fast-forwarding. 

The CrRL-X command cancels the line you're currently typing. 

Le, 

The Esc-@ command clears the display screen and leaves the cursorin  & 

ы 
the upper left corner. 


We will now discover new ways to edit program lines. These new methods are 
particularly useful when you want to make changes to programmed mode lines 
(i.e., those with line numbers). 


DELETING PROGRAM LINES 


To delete an entire line, type its line number followed immediately by a Return. 
eny am, you will see that the line and line number are no longer 
part of the program. Here is an example: 


>NEW 


2100 FRINT “VIRTUE IS ITS OWN REWARD" 

>110 PRINT "IF THE SHOE FITS, WEAR IT" 

2120 PRINT "WHERE ТНЕКЕ”5 SMOKE, THERE^S 
FIRE" 

2130 PRINT "LOOK BEFORE YOU LEAP" 

2140 PRINT "BREVITY ІЗ THE SOUL OF WIT" 
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2150 END 
2110 
2130 
>LIST 
100 PRINT "VIRTUE IS ITS OWN REWARD" 


120 PRINT "WHERE ТНЕКЕ “5 SMOKE. THER 


ESS FIRE" 

140 PRINT “BREVITY IS THE SOUL OF WI 
T" 

120 END 


You can use the command DEL to delete a block of program lines. For example: 
— ——— —-— —— ————— í—nmÓÀ—H—Óuaáití/Ü—À———Àn——Hátua—Á——— nati 


>DEL 110,140 
>LIST 
100 PRINT "VIRTUE IS ITS OWN REWARD" F 
150 END 
The command DEL 110,140 deletes all program lines starting at line number 110 


and ending with line number 140. Even though line 110 does not exist, all lines 
between 110 and 140 are deleted. 
Peake А ы с с 


ADDING PROGRAM LINES 


You can type in new program lines in any order, at any time. Their line numbers 
will determine their position in the program. The Apple II will automatically merge 
them with any other program lines currently in memory. Try adding lines 120 and 
110 back into the example above. 

2120 PRINT "WHERE THERE^S SMOKE, THERE^S 

FIRES 
2110 FRINT "IF THE SHOE FITS, WEAR IT" 
“LIST 
100 FRINT "VIRTUE IS ITS OWN REWARD" 


110 PRINT "IF THE SHOE FITS, WEAR IT 


120 PRINT "WHERE THERE’S SMOKE, THER 
E^S FIRE" 
150 END 


CHANGING PROGRAM LINES 


The simplest way to change a program line is to retype it. This is unsatisfactory 
for several reasons. Retyping is a time-consuming chore and the chances of 
typographical errors are high. Fortunately there is a way to modify program lines 
you have already typed into the computer memory. The feature of both Integer 
BASIC and Applesoft that makes this possible is that anything displayed on the 
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screen is /ive. reen. MERE кене RENE 
junction with several other keys, you can move th screen at 


will. This allows you to position the cursor to the eae of any line that is dis- 
played on the screen. Then you can use the — key to copy over unchanged parts 
of the program line. You can replace, insert, or delete characters anywhere on the 
line. 

Here is how it works. First, you use the LIST command to display the program 
line or lines you wish to change. You may have noticed that the LIST command 
puts in extra spaces when it displays program lines. (This is to make the program 
more readable.) These extra spaces can make it more difficult to edit longer pro- 
gram lines. To keep the LIST command from adding extra spaces when it displays 


program lines, clear the display screen (use Esc-@) and type the following mystery 
_“-———-——-—-——————-———————.——-———.——————.— 


command: 
—— MÀ ЕСЕ 215,335 
i, 


In addition to suppressing the extra spaces, this command reduces the width of 


the display screen from 40 char 33 characters. We will c e POKE 


statement in more detail in Chapter 4. To get the display back to normal, type: 


FOKE 223.40 


Moving the Cursor 


To.mo rsor around on the screen, you must press two keys in sequence. 


First press the Esc key and then press either the A, B, C, or D key. You must press 


Esc followed by A, B, C, or D each time you want to move the cursor one position 
right, left, down, or up. Figure 3-T illustra w the four possible key sequences 
affect cursor movemen 


With the Autostart Monitor, you can also use the |, J, K, and M keys in conjunc- 
tion with the Esc key to move the cursor. Because of the way these four keys are 
situated on the keyboard, they form a directional control pad as shown in Figure 
3-2. 


There is an important difference in the way Esc works with І, J, K, and M. Press 
Esc and the Apple ІІ goes into edit mode. Now press I, J, К, and M to move the 
———————— —— M M M ————— a À 


FIGURE 3-1. Cursor Movement (Two-Key Sequences) 
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FIGURE 3-2. Cursor Movement (Autostart Monitor Version) 


cursor around on the display screen — no need to press Esc each time. The Apple 
to move the cursor more than one space without having to retype Esc each time. 
keys. 

You can use the Rept key in edit mode to move the cursor longer distances with 


fewer keystrokes. 


Changing Characters 


Replacing one character with another is simplicity itself. Merely position the cur- 
sor on the offending character and type the replacement right over it. For exam- 
ple, with the cursor as shown: 


100 PRINT "ESTIMATED TIME ОҒ ARRIVAL" 
you can type the word DEPARTURE and get this: 
100 PRINT “ESTIMATED TIME OF DEPARTURE" 
Press Retuan to effect the change. 


Releting Characters 


You can effectively delete individual characters by typing over them with blank 
spaces. Remember that in BASIC extra blank spaces do not affect anything unléss 
they are inside of quotation marks. You can also use the Esc and A keys (the K key 
in edit mode) to move the cursor forward. ike the — , Esc-A and Esc-K do 
not recopy characters they pass over. If ne спагастетв you went 10 delete are 


inside quotation marks, it is easier to use the Esc and А keys, or the J key in edit 
mode, to skip over unwanted characters. 
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Io blank out all characters from the cursor position to the end of the display 
line, press Esc and then E. This has the same effect as pressing the space bar 
repeatedly until you reach the end of the display line, except the cursor doesn't 
ТТ if 
they were part of the same program line. For example, if you press Esc and then E 
with the cursor positioned like this: 


100 FRINT "IT IS BETTER TO HAVE LOVED AN 
B LOST THAN NEVER TO HAVE LOVED AT ALL" 


this is what happens: 


100 PRINT "IT IS BETTER TO HAVE 
D LOST THAN NEVER TO HAVE LOVED AT ALL" 


Beware! If you press Return right now, line 100 will end right where the cursor is. 
se the — key to recopy the rest of the program line. 

You can also clear all the text from the cursor position to the end of the display 
screen. To do this, press Esc and then F. 


Inserting Characters 


Inserting characters into a line is an easy process. It may seem confusing at first 
because the final results are not immediately apparent. The Apple Il cannot push 
apart characters on a line to make room for insertions. Figure 3-3 diagrams the 
way the Apple Il lets you perform insertions. You insert text above the line with the 
aid of the cursor movement keys (Esc, etc.). The thing you must remember is that 
what is displayed on the screen is not an exact replica of what is stored in the 
computer memory. 

Here is a sample editing session that demonstrates character insertion. The 


sample uses the Integer BASIC prompt character (>) but will work exactly the 
same in Applesoft. Consider the following program line: 
нан 


2NEW 


210 PRINT "ON THE WAGON" 


CD To insert the word BAND in front of the word WAGON, first list the program: 


LIST 
10 PRINT "ПМ THE WAGON" 


-. 
^ 


Using the cursor movement keys (Esc, etc.) on/y, position the cursor so that it is 
directly over the first digit of the line number, as follows: 
SLIST 
10 PRINT "ON THE WAGON" 


(32 Now use the — key to copy over the first part of the line. Stop at the W. 
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BAND 
amm, ж 


10 PRINT “ON THE WAGON” 


FIGURE 3-3. Character Insertion 


>LIST 
10 PRINT "ON THE WAGON" 


(40) Press the Esc key foll the D key to move the cursor up one line. (If there 
are characters to the right of the cursor on this line, you can erase them by press- 
ing the Esc key followed by the E key.) 

SLIST 
10 FRINT "ON THE WAGON" 


fare the word BAND. 
2L IST BAND! 
10 PRINT "ОМ THE WAGON" 


©); Using only the cursor movement keys, position the cursor over the first letter of 
the insertion. Dg not use the — key to back the cursor up. Although it looks like it 


does the same thing on the display screen as Esc-B or sc-J, — actually erases 


the characters it ver; it will un-insert your insertions! 
c A ey 
2,457 BAND 


10 PRINT "ON THE WAGON" 


C3 Press the Esc key followed by the C key to return the cursor to the original pro- 
gram line. 
SLIST BAND 
10 FRINT “ON THE WAGON" 


€» Finally, use the — key to copy over the rest of the line. Then press RerunN. Display 
the new line with the LIST command. 


JZLIST BAND 
10 PRINT "ON THE WAGON" 


2LIST 10 
10 PRINT "ОМ THE BANDWAGON 


Appendix B contains a handy reference table of editing commands. 
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REEXECUTING IN IMMEDIATE MODE 


The fact that anything on the Apple ІІ display screen is live allows you to reex- 
ecute any immediate mode statements that are still visible on the display screen. 
You can reexecute an immediate mode statement just as it is, or you can edit it 
first. 

In either case, the first thing to do is to position the cursor to the beginning of 
the immediate mode line. Use the Esc and A, B, C, D keys alternately as described 
above (ог Esc followed by any number of |, J, K, and M keys if you have ап 
Autostart Monitor). Then use the — key to copy over the immediate mode 
instruction. You can, of course, make changes to the line using the techniques we 
have just described for replacing, deleting, and inserting characters on a line. 

To see how this works, look at the following immediate mode program which 
calculates the cubic feet of storage space in a 10 X 25 X 8 foot room. 

>PRINT "CU. FT. OF SFACE = ":i10s25«8 
CU. FT. OF SPACE = 2000 


You can change this immediate mode program easily to calculate the storage 
space in rooms of different sizes. To change the dimensions to 10 X 25 X 14, 
for example, first position the cursor to the beginning of the immediate mode line. 
(Alternately press Esc and D three times.) Now press and hold the — key while you 
hold down the Верт key. The cursor will fast-forward along the immediate mode 
line. Release both keys in time to stop the cursor when it gets to the 8. If you over- 
shoot or undershoot by not releasing the keys at the proper time, you can move 
the cursor back and forth one character at a time with the — and — keys. For that 
matter, you could move the cursor from the start of the line to the 8 by pressing 
the — key 33 times, instead of using the Reet and — keys in conjunction. 
With the cursor positioned over the 8, type in the new room dimension of 14 

and press Return. 

ЭРБІМТ "CU. FT. OF SPACE = "510425414 

CL. FT. ОЕ SPACE = 3500 


PROGRAMMING LANGUAGES 


A j i ium of communication between you and the 


computer. There are many different programming languages. Some, like BASIC, 
are general purpose languages, while others are designed to make it easy to write 
programs in specific areas like business, science, graphics, text manipulation, and 
so forth. Programming languages are as different as spoken languages. In addition 
to BASIC, other common programming languages are Pascal, C, FORTRAN, 
COBOL, APL, PL/M, PL-1, and FORTH. 

Apple ІІ computers can use several programming languages, BASIC and Pascal 
among them. This book concentrates on describing how to program the Apple Il in 
BASIC. 
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No matter what the programming language, every program statement must be 
written following a well-defined set of rules. These rules taken together are re- 
ferred to as syntax. ifferent programming language has its own syntax. 

Programming languages, like spoken languages, һауе dialects. Dialects 
manifest themselves as minor variations in syntax. The Apple ЇЇ has two such 
dialects of BASIC: Integer BASIC and Applesoft. Because of the differences be- 
tween the two dialects, very often programs written in one dialect will not work 
correctly when the Apple ll is expecting instructions in the other dialect. Further- 
more, a BASIC program written for the Apple ІІ may not run on another computer, 
even if the other computer also claims to be programmable in BASIC. However, 
having learned how to program your Apple ll computer in either of its BASIC 
dialects, you will have little trouble learning any other dialect of BASIC. 

Some programming language syntax rules are obvious. The addition and 
subtraction examples at the beginning of this chapter use obvious syntax. You do 
not have to be a programmer to understand them. But most syntax rules are 
utterly arbitrary and meaningless, until you have learned the syntax. You should 
not try to seek a rationale for syntax rules; usually there is none. For example, why 
use «to represent multiplication? Normally, you would use an X for multiplication. 
But the computer would have no way of differentiating between the use of X to 
represent multiplication and to represent the letter X. Therefore, nearly all com- 
puter languages have opted for the asterisk (*) to represent multiplication. Division 
is universally represented by the / sign. There is no real reason for this selection; 
the division sign (+) is not present on computer keyboards, so some other 
character must be selected. 


ELEMENTS OF BASIC 


Most of the syntax rules for BASIC concern individual statements. BASIC state- 
ment syntax deals separately with its three major elements: line numbers, instruc- 
tions to the computer, and data. We will describe each in turn. There are also а 
few rules that pertain to the program as a whole, such as statement order. We will 
cover these rules in appropriate places throughout the chapter. 


LINE NUMBERS REVISITED 


We've already talked about line numbers to some extent. After a brief review, 
we'll go into more detail. In programmed mode, every line of a BASIC program 
must have a unique line number. Line numbers determine the sequence of instruc- 
tions in a program; the statement with the lowest line number is first and the 
statement with the highest line number is last. 


Integer BASIC allows one- to five-digit line numbers with integer values be- 


tween O and 32767. 
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Applesoft allows one- to five-digit line numbers with integer values between O 
and 63999. B 


Line Numbers as Addresses 


In essence, line numbers are a way of addressing program lines. This is an impor- 
tant concept, since every program will contain two types ts: 


1. Statements which create or modify data, and 
2. Statements which control the sequence in which operations are 
performed. 


The idea that operations specified by a program must be performed in some 
well-defined sequence is a simple enough concept. Normally, program execution 
begins with the first statement in the program and continues sequentially, as 


illustrated below. 
Start 10 
2022 


30 

407 
Co 

etc: 


But we will soon discover that most programs contain some non-sequential 
execution sequences. That is when line numbers become important, because you 
can use a line number to identi in execution sequence. This may be 


illustrated as 


Start ——-10 
22 
C ao 
207 GOTO 70 
50 ^ 


BLANK SPACES 


Generally speaking, you can use extra blank spaces freely to improve the 

—readability of your program. But because each extra space would take extra 
- M Rr cE . 

memory, the Apple ll compresses unnecessary blank spaces out of a program line 

ee 
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when you enter it (and press Return). Then when you display program lines with 
the LIST command, the Apple II reinflates them with blank spaces for readability, 
according to a predetermined plan. Recall that you can suppress the reinflation by 
typing POKE 33,33 before issuing a LIST command. ,40 normalizes 


display screen. 


You do have to be careful about using extra spaces within quotation marks. 
Compare the following two commands, for example: 


PRINT "ENTER INVOICE DATE" 
ENTER INVOICE DATE 


PR INT " ENTER INVOICE D ATE" 
ENTER INVOICE © ATE 


DATA 


The main business of computer programs is to input, manipulate, and output data. 
So the way a programming language handles data, whether it be numbers or text, 
is very important indeed. We will now describe the types of data you may 
encounter in an Apple ІІ BASIC program. 2: 


Strings 
—nnÀ 


A string is any character or sequence of characters enclosed in quotation marks. 
We have already used strings with the PRINT statement as messages to be dis- 
played on the screen. Here are some more examples of strings: 

"IGNORANCE 1S BLISS" 

"ACCOUNT 4019-181-324-837" 

"NICK CHARLES" 

"SAM & ELLA CAFE" 

"MARCH 18, 1956" 


With just a few exceptions, a string can contain any character you can produce 
at ihe keyboard using the normal alphabetic and numeric keys, with or without the 
keys. T аге —, —, Return, Esc, CrRL-H, CrnL.-M, Crat-U, 
and Crm-X. These exceptions either move the cursor around or end the Tine 
you're working on, or both. 


Strings can be any length from O to 255 characters. A string with no charac- 


ters in it is called the nu// string. 

There are some invisible characters you can produce by pressing certain com- 
the computer beeps. You can put this character in a string. Try using some of 
these characters with a PRINT statement. 


PRINT "" Press CrnL-G several times between 
the quotation marks 
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In this example you can hear the character even though you can't see it. There are 


othe invisible and inaudible. Such characters are use n- 


trolling printer functions, communications devices, and other components you 
a— — — Ah е ра — —— — n ERI RÀ — 


càn attach to the Apple ll. 
— > Appendix | lists the entire Apple ІІ character set and tells you which keys pro- 


duce which characters. 
In Applesoft there is a way you can include, in a string, characters which you 


cannot generate directly by pressing keys. You do this with the CHR$-fufiction, 


which we will describe in Chapter 4. 


Numbers 

Тпеге are two kinds of numbers Mar сап De stored in the Appiè (2 integers. which 

are numbers without any fractional part, and rea/ numbers (also called floating 

epoi perai whioh ово hava пас а а. As you might suspect, Integer 

BASIC only recognizes integers. Applesoft uses both integers and real numbers. 
You must express all numbers without commas. a 6, you must use 

32000, not 32,000. 


Integers 


An integer is a number that has no fractional portion or decimal point, The number 
can be negative (-) or positive (+). Ап unsigned number is assumed to be positive. 


Integer numbers must have values in the range —32767 to 32767. The following 
are examples of integers: 


Real Numbers 


A real number can be a whole number, a whole number wi decimal ion, or 
just a decimal fraction. The number can be negative (-) or positive (4-). If the num- 
er has no sign it is assumed to be positive. The smallest (most negative) real 
number is: 
—100000000000000000000000000000000000000 -/ 23% 
and the largest is: 
100000000000000000000000000000000000000 +5) 
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Here are some examples of real numbers: 
5 
-15 
65000 


0.5 
0.0165432 
-0.0000009 


When the value of апу fractional number gets closer to zero than about 
.000000000000000000000000000000000000003, it will be converted to 


zero. 


Scientific Notation 


Very large and very small real numbers are represented in Applesoft using scien- 
tific notation . Any number that has ine digits in front of the decimal 
point will be expressed in scientific notation. Any fractional number closer to zero 


than 2.01 will be expressed in scientific notation. 


A number in scientific notation has the form: 
number Et ee 
——— 


where: number is ап integer, fraction, or combination, as illustrated above. 
Ps — Wu nce] TTY PIE AGE VARE T ES CET OB Re У-у. 
The numb rtion contains the number's significant 
digits; it is called the coefficient .If no decimal point 
appears, it is assumed to be to the right of the coefficient. 


is always the letter E. It stands for the word exponent. 


is an optional plus sign or minus sign. 
is a one-digit or two-digit exponent. The exponent specifies 


the magnitude of the number, that is, the number of places 
to the right (positive exponent) or to the left (negative 
exponent) that the decimal point must be moved to give 
the true decimal point location. 


| ji+ |m 


Here are some examples of scientific notation: 


Standard Notation Scientific Notation 
1000000000 1E+09 
.000000001 1E - 09 
-123456789 —1.23456789E + 09 +о $ 


-.00000123456789 —1.23456789E - 06 
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As you can see, scientific notation is a convenient way of expressing very large 
and very small numbers. The maximum and minimum values for real numbers, 
which we just expressed with lots of zeros, can also be expressed as 1E+38 and 
—1E-438, respectively (much more compact). Similarly, the closest a number сап 
get to zero is 3E-38. 


Roundoff 


We mentioned earlier in this chapter that real numbers can have as many as nine 
digits of precision. For a number greater than 1 or less than - 1, this теспе only 
the leftmost nine digits can be nonzero. The Apple Il rounds off any digits in 
excess of nine. Here are some examples (note that large numbers print in scientific 


notation): 
JPRINT 1234567391 
1. 23454789E+09 


12-122428789123456789 
-1.23456789Е%17 


17-150000475.79 
-150000476 


1790000000. 7558 
90000000.3 


Fractional numbers (those between 1 and —1) are subject to the same limita- 
tion. In this case, though, the nine digits of precision start with the first nonzero 
digit to the right of the decimal point. Here are some examples: 


ІРКІМТ .1234567891 
.123456739 


37-1234567891 234256789 
-1.23450789Е%17 


12-1223456789 123456789 
-1.23456789Е+17 


1?.000000000900000007558 
9. 00000003Е-10 


VARIABLES 


Thus far in our discussions of data we have only considered constant values. It is 
often handier to refer to data items by name rather than value. That is what varia- 
bles are all about. 

If you have studied elementary algebra, you will have no trouble understanding 
the concept of variables and variable names. If you have never studied algebra, 
then think of a variable name as a name which is assigned to a letter box. Any- 
thing which is placed in the letter box becomes the value associated with the let- 
ter box name, until something new is placed in the letter box. In computer jargon 


Chapter 3: PROGRAMMING IN BASIC 63 


we say a value is stored in a variable. 


jns, т um 
Dom a Dp - 

IL Шоо ШУЙДЕ 
1 шо Штаты їй 


A variable does not always have to refer to the same value. That is its real 
power — it can represent any legal value. You can change its value during the 
course of a program. BASIC has a number of statements to do this; we will de- 
scribe them later. 


Integer BASIC Variable Names 


Variable names in Integer BASIC can have 1 to 100 characters. These are the 
general rules for constructing Integer BASIC variable names: 
MÀ ————————— À 


OO0---oo 


| о Б; 
Last character must bd $) or string variables 
© ; : 


Second, third, fourth, etc. characters (optional) can 
be any letter or digit 
First character must be a letter * 


ч Thus the last character of the variable name tells Integer BASIC which type of 
the variable represents — string or numeric. 


String variables can refer to strings of h between 55 charac- 
ters. Blank spaces in a strin count towards its total length. Before you use a strin 


length it will 

escribe later. If you fail to do so, you will get a 
+++ STR OVFL ERR message. Here are some examples of string variable names, 
legal and illegal: 


Legal Illegal 

A$ $ 
СО5ТМАМЕФ 9% 

PART1$ BRAND.NAME$ 
RESPONSE$ 


X8$ 
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ric variables in Integer BASIC must have values between —32767 and 
+32767. If you surpass these bounds, you will get the ««« > 32767 ERR 
message. Here are some examples of numeric variable names in Integer BASIC, 
both legal and illegal: 


Legal Illegal 

A APPLICANT'S AGE 
CUSTZIPCODE 3X4Z 

XO $TOTAL 


Variable Names in Applesoft 


A variable name can have one, two, or three characters in Applesoft. The follow- 
и rules apply: 


tes variable type: 
$ for fors pus wee 
?6 for integer for integer variable 
real variable otherwise 
I. mr character рот ораған) uir can be 
any letter or any letter or digit — ——~ 


VD cst character must be a letter ^Y 
WIL Б ilios oiii scade 
Thus the last character of the variable name tells Applesoft which type of data the 
variable represents. 


A string variable in Applesoft can store a string value of any length from O to 
255 characters. You do not specify a maximum string length as in Integer BASIC; 


Applesoft does not need it. Here are some examples of string variable names, 
both legal and illegal: 


Legal Illegal 
A$ o$ 
MN$ MI$ 
F6$ 77$ 


Integer variables can refer to whole numbers between -32767 апа +32767. 
If you attempt to exceed this limit, you will get the ?ILLEGAL QUANTITY ERROR 
message. If you try to store a real value in an integer variable, Applesoft will con- 


vert the real value to an integer value first. We'll cover the rules for the conversion 
shortly. Here are some examples of legal and illegal integer variables in Applesoft: 


Legal Illegal 
A96 A$% 
B% 31% 
A1% 3D% 


X4% 
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Real varies can refer to numeric values generally restricted to the range 
en in iiu Үч + or —) under some circumstances. If you attempt to stare 
(in a real variable) a value that is too large in magnitude you will get the ?OVERF- 
LOW ERROR message. 


When the value of a real variable gets closer to zero than 2.9388 X 10-39, 
Applesoft converts it to zero. 


Remember, real variables can have integer values, since ап integer-is-a real 
number with a fractional part of zero. Here are some examples of real variables 
(legal and illegal): Legal Illegal 

A 0 
В 7B 
A1 A+ 
AA 

25 


Longer Variable Names іп Applesoft 

Variable names can actually have more than two alphanumeric characters (pius 
the % or $ suffix for integer- and string-type variables], but only the first two 
characters count in Applesoft. Therefore, PRICE1 and PRICE2 are the same name, 
have different type suffixes. 


Applesoft allows variabl 
ere are some examples of variable names with more than two characters: 


Legal Illegal 

COUNTER% ІТЕМЗЕ% 
ACCOUNTBALANCE 2NDRATE 

NAME$ CUSTOMER. ADDRESS$ 


Keep the following points in mind if you use variable names with more than two 
characters: 


1. Only the first two characters and variable type suffix ($ or %) are 
significant. Do not use extended names like LOOP 1% and LOOP2%; 
these refer to the same variable: LO%. 

2. Additional characters need extra memory space, which you might 
need for longer programs. But the advantage of using longer variable 
names is that they make programs easier to read. PARTNO, for 
example, is more meaningful than PA as a variable name describing 
part numbers in an inventory program. 


Reserved Words 


Tu 
All of the words that define a B statement's rations are called reserved 


words. Appendix F lists all Integer BASIC and Applesoft reserved words. You will 
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have encountered many of these reserved words in this chapter, but others are 
described elsewhere in this book. 

When executing BASIC programs, the Apple ІІ scans every BASIC statement, 
seeking out any character string that constitutes a reserved word. The only excep- 
tion is t rings enclosed in quotes. This can cause trou a reserved word is 
embedded anywhere within a variable name. The Apple ІІ is not smart enough to 


identify a variable name by its location in a BASIC ement. Therefore you must 


be very careful to keep reser rds out of your variable names; this is particu- 
larly important with the short reserved words that can easily slip into a variable 
name. 

ARRAYS 


rrays are really nothing more than a systematic way of naming a large number of 
variables. They are used frequently in many types of computer programs. If you 
do not understand what arrays are, or how to use them, then read on; the infor- 
mation that follows will be very important to your programming efforts. 


Conceptually, arrays are very simple things. When you have two or more data 
items, instead of giving each data item a separate variable name, you give the col- 
lection of data items a single variable name. The collection is called an array, its 
elements in an array are numbered. You select an individual item using its position 
number, which is referred to as its index. 

Arrays are a useful shorthand means of describing a large number of related 
variables. Consider, for example, a table of 200 numbers. How would you like it if 
you had to assign a unique variable name to each of the 200 numbers? It would 
be far simpler to give the entire table one name, and identify individual numbers 
within the table by their table location. That is precisely what an array does. 

As an example of array usage, consider how a motel with ten rooms might 
keep track of who is staying in each of its rooms. There could be a separate varia- 
ble name for each room. 


JONES | SMITH E LITTKE | ALTON | DAVIS ol. - 


R1$ R2 R5$ R6$ R10$ 


Or you could consider the motel guest list an array. 


| JONES | SMITH \оо | | LITTKE | ALTON | DAVIS |НАМ5ОМ SHORTEN] | 


R$(1) А$(2)  R$(3) R$(4)  R$(5) Н%(6)  R$(7  R$(8  R$(9)  R$(10) 


In this example, R$ is an array name. It has ten elements; each element js the 


me oft uest i t : index lenc heses) follows 
each variable n . Thus ifi ta item (i.e., the quest in oner is iden- 


pr tified by a variable name and an index. The guest in the third room is the value of 


R$(3), which is DOE. 
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The array examples above all use string arrays because strings are easier for 
most pe intuitivel сег Integer BASIC only allows numeric 


arrays. 

Arrays in lesoft can represent integer variables, real variables, or string 
variables; however, a single arr i ent one data type. In 
other words, a single vari mix integer and real numbers, except in the 
sense that a real variable i value (but not vice versa). Each type 


of array uses a different amount of memory; see Appendix G for details. 


Array Dimension(s) 


"А You must specify the number of elements in an array before you use it in Integer 
BASIC. You do this wit mension) statement. Dimension statements are 


described later in this chapter. 


Applesoft lets you use arrays wi о е! і t dimensioning 
hem first. 


Applesoft arrays can have more than one dimension, which means that it will 
individual ele ar i 


take more than one index to select an a single 

imension is equivalent to a table with just one row of num i 
tifies a number within the single row. An 
ordinary table ers with rows and columns; one index i 


ifies the row, 
the other index identifies the column. You can visualize an array with three dimen- 
sions as a cube of numbers, or perhaps a stack of tables. Four or i ions 
yield an array that is hard to visualize, but mathematically no more complex than a 


smaller dimensioned array. 


We can create an example of a two-dimensional array by extending the pre- 
vious example of the motel guest list. Consider an eight-floor hotel with ten rooms 
on each floor. There are four options for keeping track of the 80 guests’ names. 
First, each room could have its own variable. Second, the hotel could have one 
80-element array. Third, each floor could have a separate ten-element array. 
Fourth, the hotel could have one two-dimensional array. This final choice may be 
illustrated as follows: 


СЕ 
вилт явил [наи [vsu nous [ses [vsum [vem нама [ess 
ал [ssa [ss [ssa назв [нав [нал [vsum наза sso 
sm Pisa [ss usea [asa [vse [sn [vem | нава [sir 
ШЕИСЕИСЕНСІЕИСЕСІЕИСЕЛСЕНСІГІСІС) 
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As you can see, the first index of this two-dimensional array is the floor number, 
and the second index is the room number on that floor. So R$(3,2) would be the 
name of the guest in the second room on the third floor. 

lesoft arrays can have up to 88 dimensions. There is no specific limit on 
the number of elements in each dimension. The amou emory available will 


limit the total number of elements, of course, since each element requires a cer- 
pog purum TPIT KNEES агнуур —' "a 
tain amount of memory space. 

———————————_ 


EXPRESSIONS 


In the following section we will explore ways in which you can combine the values 
of variables and constants by using express/ons. We have already used expres- 
sions to calculate the value of simple arithmetic problems in immediate mode. 


Recall that the statement 
PRINT 4+4 


10 


tells the Apple ІІ computer to add 4 and 6, and then display the sum. The state- 
ш PRINT A+E 
о 

tells the Apple ll computer to add the values of the two numeric variables А апа B, 
and then display the sum. 


The plus sign (+) specifies addition. Standard computer jargon refers to the 
plus sign as an operator. The plus sign is an arithmetic operator because it 


specifies addition, which is an arithmetic operation. 

Arithmetic operators are easy enough to understand; we all learn to add, 
subtract, multiply and divide in early childhood. But re other types of opera- 
tors: string operators, relational operators, and Boolean operators. These are also 
easy to understand, but they take a little more explanation since they involve more 
abstract notions. 

Each category of operators defines a type of expression. There are arithmetic 
expressions, string expressions, relational expressions, and Boolean expressions. 


Precedence of Operators in Expressions 


Expressions can call for more than one operation to occur. For example, this state- 
кенен PRINT A+B/10 

о 
calls for both addition and division іп the same expression. There is a standard 
scheme for determining in what order to a an expression. We will lay out 
these rules of precedence ch t ith strin n- 


catenation, then int an, and mixed-type expressions, in 


that order. First let's look at a way to override the standard precedence rules. 
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Overriding Standard Precedence 
You can change the order in which the Apple ІІ evaluates expressions through the 
use of parentheses. Any operation within parenthasss is performed Tat Whar parentheses. Any operation within parentheses is performed first. When 
more than one set of parentheses is present, the Apple Il evaluates them from left 
сөне... E A 
When one set of parentheses is enclosed within another set, it is ing. 
etc, Parentheses can be nested to any level. You may use them freely to clarify the 
order of operations being performed in an expression. 


Here are some examples of the immediate mode arithmetic calculations using 


parentheses: PRINT (2+10) #3 
36 


2 
^ 


PRINT ((2*10)42431)910 
570 


> 
PRINT -(2%53%5/4)) 
-32 


String Concatenation 


You can join strings together end to end, to form one longer stri isis called 


concatenation. You can visualize this as follows: 
hd dade eo 


STRINGI Ф STRING2| + 


Весотеѕ 
<> 
STRING1|STRING2|STRING3 
With concatenation, you can develop strings up to 255 characters long. 
Integer BASIC has no concatenatio rator. You can concate ings in 


Integer BASIC by using a technique explained at the end of this chapter (introduc- 


ing it here would be premature). 
Applesoft uses the plus sign (+) as а co enation operator. Here are some 
examples of string concatenation in Applesoft. 


"OVER" + "DUE" becomes “OVERDUE” 

“MONTHLY” +” ” + “REPORT” becomes | "MONTHLY REPORT" 

“WEEKLY” + R$ becomes the characters WEEKLY followed 
by the value of R$ 

А1$ + YAS + C$(1) becomes the value of A1$ followed by the 


value of YA$ followed by the 
value of C$(1) 
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Integer Expressions 


Integer expressions are arithmetic expressions which involve only integer varia- 
bles and integer constants. We will cover arithmetic expressions involving both 
integer and real values under the heading “Міхеа-Туре Expressions.” 

The operators for integer expression are addition (+), subtraction (-), multi- 


plication (*), division (/), and exponentiation (^). You can also use a unary minus 


(-) to indicate a negative numeric value. Operations are performed in this order: 
unary minus first, followed by exponentiation, multiplication and division next, and 
finally addition and subtraction. Operations of equal precedence are performed in 


order from left to right. 


Here are some examples of integer expressions in Integer BASIC: 


100-30»ж2 results іп 40 
-9^2 resultsin 81 
A/B*C resultsin the value of A divided by the value 


of B and the integer value of the 
quotient multiplied by 
the value of C 


D 4-X*3 resultsin three times the value of X and 
the value of D added to that product 
5/242 resultsin 4 (the quotient of 5/2 is converted 


to the integer 2) 


Here are some examples of integer expressions in Applesoft: 


—120/2 + 100 resultsin 40 

2^ 3+2 resultsin 16 

N1?6* N296/N 396 resultsin the value of N1% times the value of N2% 
and the product divided by N3% 

AA%/AB%/AC% resultsin the value of AA% divided by the 


value of AB% and the quotient 

divided by the value of AC% 
5/2*2 resultsin 5 (the quotient of 5/2 is 

not converted to an integer) 


Integer BASIC has one г you can use in integer expressions. It 


returns the remainder that is left over from a division operation where the dividend 
is not evenly divisible by the divisor. T tor is . It has equal precedence 
with multiplication and division. Here are some examples of MOD: 

EE E E CCS CIC ee 


4 MOD 3 resultsin 1 
3*5 MOD 4 resultsin 3 


(41+2)/25 MODA  resultsin the remainder after 
dividing 18 by the value of A 
3 MOD 4 resultsin 3 
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Real Expressions 


Applesoft has another kind of arithmetic expression; it yields a real value. Its 
operators are the same as those in Applesoft integer expressions: addition (+), 
subtraction (—), multiplication (ж), division (/), exponentiation (^) and unary 
minus (-). The precedence of operation is the same also: unary minus first, 
followed by exponentiation, multiplication and division, and finally addition and 
subtraction. Here are some examples of real expressions: 


87.5 - 4,25ж2 resultsin 79 
1.5 ^ (3/2/2) resultsin 1.35540301 


AL*(PL —3.1*CB) resultsin the value of AL times the 
result of subtracting the 
product of 3.1 times the value of 
CB from the value of PL 

7.5*2/5 results іп 3 


Relational Expressions 


Relational operators allow you to compare two values to see what relationship 
one bears to the other. You can compare whether the first is greater than, less 
than, equal, not equal, greater than or equal, or less than or equal to the second 


value. The values you compare can be constants, variables, or any kind of expres- 


sions. (There are some restrictions in Int one side of a 
relational operator is a aa the value on the other side. must be a string also. 
лелиіве, you сап compare ona type oF маше: to апос ра using-relatigna 
operators. 

If the relationship is true, the relational expression has a nu i lue of 1. If 


the relationship is false, the relational expression has the value O. 
The relational operators for Integer BASIC and Applesoft are the same, with 


one exception, as shown in Table 3-1. 


> TABLE 3-1. Relational Operators 


Integer BASIC à Applesoft 


Less Than* 

Greater Than” 

Equal To 

Not Equal To <>ог >< 
Greater Than or Equal То" > = ог = > 
Less Than or Equal То” <= ог < 


*Not allowed with strings іп Integer BASIC. 
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All relational operators have the same precedence; they are evaluated in order 
from left to right. 
Here are some examples of relational expressions: 


125-4 resultsin 1 (true) 
14 » 66 resultsin О (false) 
15: >= 15 resultsin 1 (true) 
"AA" > “ДА” results in O (false) 
"ANDERSON" < “ASHLEY” results in 1 (true) 
(A 2 B) - (A$ > В%) depends оп the values of the variables. 


If the value of A is equal to the 
value of B and the value of 
AS is greater than the value 
of B$, then this expression 
results in 1 (true). 


The concept behind relational operators is easy enough to understand. The 
values O and 1 which BASIC arbitrarily assigns to false and true conditions can be 
used in integer and real expressions. This is not so easy to understand, since it is 
utterly ees a ghe ting мены Trl ud Fons 
Outside of a BASIC program such an expression would be meaningless; but 


same as 1*4, which results іп 4/ You can include relational expressions within 
——————M— ——Mále елена — — A — а кенеді 
other BASIC expressions. Here are some examples: 


25 + (14 >66) is the same as 2540 
(A-(125-4)«(15 > = 15) is the same as (A + 1) *(1) 


String Comparisons 


You may be wondering what rules the Apple ІІ uses when it compares strings. 
There are two considerations. First is string length. Strings of unequal length 


(remember blanks count toward string length) are not equal. If a shorter string is 
identical to the first part of a longer string, the longer string is greater than the 
horter s this is only pertinent in Applesoft). The second consideration is 


whether the strings contain the same characters, in the same order. In Integer 
BASIC, you cen шы оширара-5иа аш Ша wh the = and O operators Sings sre 
com one character at a time, starting with the leftmost character — the first 
cha f one string with the first character of the other, the second character 
with the second character, Third with thesi end ac am unilTone ере seme i 
exhausted or a character mismatch occurs ~ ——————————— — —— -— 
Applesoft will compare the relative ordering of characters one by one. For com- 
parison purposes, the letters of the alphabet have the order A>B, B>C, C>D, 
etc. Numbers that appear in strings have conventional ordering, namely O^» 1, 


122,223, etc. Other characters that appear in strings, like +, —, $, and so оп, 
are arbitrarily ranked іп the order shown in Appendix 1. 
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TABLE 3-2. Boolean Truth Table 


The AND operation results in a 1 only if both values are 1. 


1 AND 1 = 1 1 ANDO = 0 
0 AND 120 0 ANDO = 0 


The OR operation results in a 1 if either value is 1. 


10R121 1ORO=1 
OOR1=1 OORO=0 


The NOT operation logically complements each value. 
NOT 120 
МОТ О = 1 


Boolean Expressions 


Boolean operators give programs the ability to make logical decisions. Hence they 
are often called /og/ four standard Boolean operators: 
AND, OR, Exclusive OR, and NOT. BASIC on the Apple ІІ supports three of these 


operators: AND, OR, and МОТ. 


If you do not understand Boolean operators then a simple supermarket shop- 
ping analogy will serve to illustrate Boolean logic. Suppose you are shopping for 
breakfast cereals with two children. The AND Boolean operator says you will buy 
a cereal if both children select that cereal. The OR Boolean operator says that you 
will buy a cereal if either child selects it. The NOT Boolean operator generates an 
opposite. If child B insists on disagreeing with child A, then child B's decision is 
always the NOT of child A's decision. 

Computers do not work with analogies; they work with numbers. Therefore 
Boolean logic reduces the values it operates on to 1 or O (true or false). Since Boo- 
tional expressions (remember that relational expressions result in the value O or 
1 oolean operators can work on other types of operands, as we shall see 
shortly in the next section. 

Table 3-2 summarizes the way in which Boolean expressions are evaluated. 


This table is referred to as a truth table. Boolean operators have equal prece- 

dence. If more than one Boolean operator is present in the same expression, they 

are evaluated from left to right. Here are some examples of Boolean expressions: 
NOT ((3 + 4) > = 6) results in О (false) 


("AA" = AB") OR ((8#2) = 4^2) resultsin 1 (true) 


NOT ("APPLE" = ‘‘ORANGE”) 
AND (A$ = B$) resultsin 1 (true) if A$ and B$ 
are equal; O (false) if not 
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Mixed-Type Expressions 


Very often expressions will not involve values of just one type. This is especially 
true in Applesoft, which has both integer and real numeric types. We have already 
introduced the idea of mixed-type expressions in our discussion of relational and 
Boolean expressions. You can mix types freely in any expression, except that 


strings cannot be part of integer, real, or Boolean expressions. Strings can only be 
present in string and relational expressions. Here are some examples of mixed- 


type expressions: 


Legal Illegal 

3.1416 *(R ^ 2) 1600 + "PENNSYLVANIA AVENUE" 
A% > = B/3 ST$ <А% 

43 AND 137 A$ AND B$ 

1 ОВДЕ +10 NOT (A$) = B$ 


(A$ = B$) АМО -6.25 МОТ(А = В) ОВ С$ 


The Apple ІІ has several things to resolve when it evaluates a mixed-type 
expression. The first issue is the precedence of operators. Table 3-3 summarizes 
the operators for all types of expressions in order of precedence, from highest to 
lowest. This table shows us that anything in parentheses is evaluated first. If there 
is more than one level of parentheses present, the Apple ІІ evaluates the inner- 
most set first, then the next innermost, etc. (You will recall we covered this con- 
cept of nesting earlier.) Next, arithmetic expressions are evaluated. After that, 
relational expressions are evaluated. Finally, Boolean expressions are evaluated. 


TABLE 3-3. Operators 
Integer BASIC Applesoft BASIC . 
Parentheses denote order of 
evaluation 


Exponentiation 
Unary Minus 


Precedence 


r 
i T mn 


Arithmetic ; aoe 
oparata not available Division Remainder ** 
Addition 


Subtraction 


Equal 

Not equal 
Relational Less than 
Operators Greater than 

Less than or Equal 


Greater than or Equal 


Logical complement 
Logical AND 
Logical OR 


Boolean 
Operators 


** Integer BASIC only 
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As we noted earlier, relational expressions return a value of O or 1 depending 
FAND Uc DumBOBA WENNS GRE RG тақ тыға WERUCLNUOUOECGU GY PRESEN HIN ERE OES RA GNE erreur 
on whether the relationship being tested is false or true. Thus, a relational expres- 

sion can exist as part of an integer or real expression. 


You can also mix types in Boolean expressions. Everything in a Boolean expres- 
sion is convertad 1а 0 or 1 before апу Boolean operations take place Numeric 
values are converted according to the following rule: if the value is O, it remains 
zero; any non-zero value is converted to 1. 


BASIC cannot automatically convert strings to numeric values, so strings are 
—Á— —— — — ————————————————— 


illegal in integer, real, and Boolean expressions, except as part of a relational 
expression. 


In Applesoft both integer and real values can be present in the same real, rela- 


ional, or Boolean expression. 

Whenever they occur in a real expression, integer values are converted to real 
values temporarily in order to evaluate the expression. The final result of such an 
expression can be either an integer value or a real value, depending on the context 
in which the expression occurs. Applesoft will convert the value automatically as 
appropriate. 


Ж Real values аге converted to integers by discarding the fractional part and using 
the next lower whole number. This is called truncation. For example: 
———————————— n—A Áá— ——— 


L1 becomes 1 
1.9 becomes 1 
—1.1 becomes -2 
-1.9 becomes -2 


BASIC STATEMENTS 


We are now ready to describe the part of the BASIC statements which specifies 
the operation the statement will perform. You specify these operations with 
BASIC instructions. It is common practice to use the terms statement and сот- 
mand interchangeably and somewhat ambiguously. Strictly speaking, a command 
is an instruction issued in immediate mode. The same instruction in programmed 
made.is a statement. 

Each instruction performs a specific task. This chapter introduces you to pro- 
gramming concepts, stressing the way statements are used. We do not describe 
statements in detail in this chapter. Be sure to read the complete statement 
description given in Chapter 8 to get a thorough understanding of how a state- 
ment works. This chapter will give you an understanding of only part of a state- 
ment's total capabilities. 

One last caveat before we begin. Although this chapter introduces you to pro- 
gramming concepts, it cannot possibly cover programming in depth. If you want 
or need more instruction in programming, consult one of the BASIC primers listed 
in Appendix K. 
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REMARKS 


It is appropriate that any discussion of BASIC statements begins by describing the 
only.BASIC statement which the computer will ignore: the remark. If the first three 


characters of a BASIC statement are REM, then the computer ignores the state- 
ment entirely. So why include such a statement? The answer is that remarks 
make your program easier to read. 

' If you write a short program with five or ten statements, you will probably have 
little trouble remembering what the program does — unless you leave it around 
for six months and then try to use it again. If you write a longer program with 100 
or 200 statements, then you are quite likely to forget something very important 
about the program the very next time you use it. After you have written dozens of 
programs, you will stand no chance of remembering each program in detail. The 
solution to this problem is to document your program by including remarks that 
describe what is going on. 

Good programmers use plenty of remarks in all of their programs. іп all of this 
chapter's program examples we will include remarks that describe what is going 
on, simply to get you into the habit of doing the same thing yourself. 


Remark statements have line num lik ot t. A remark 


statement's line number can be used like any other statement's line number. 


ASSIGNMENT STATEMENTS 


Assignment statements let you assign values to variables. You will encounter 
assignment statements frequently, in every type of BASIC program. 
Here is an example of an assignment statement: 
9?O REM INITIALIZE VARIABLE X 
100 LET X=3 
In statement 100, variable X is assigned the value 3; this same statement could 
be rewritten: 


100 X=3 
The word LET is optional; usually it is omitted. 
Here is a string variable assignment statement: 
215 AS="ALSQ RAN" 


The string variable A$ is assigned the two words ALSO RAN. 
Here are three assignment statements that assign values to array variable R$(), 
which we encountered earlier when describing arrays: 
200 КЕМ R$() IS THE MOTEL GUEST LIST 
210 R$(1)="JONES" 


220 R$(2)="SMITH" 
230 R$C3)2"DOE" 


Remember, we can put more than one statement on a single line; therefore the 


Chapter 3: PROGRAMMING IN BASIC 77 


three R$ assignments could be placed on a single line as follows: 
200 REM R$() IS THE MOTEL GUEST LIST 
210 R$(1)="JIONES":R$(2)="SMITH"'R$(3)="D0E" 
I n must separate adj ents appearing on the sa i 
Assignment statements can include any of the arithmetic or logical operators 
described earlier in this chapter. Here is an example of such an assignment state- 
ment: 
vo REM THIS A DUMB WAY OF ASSIGNING A VALLE 
100 V=33+7/? 
The statement above assigns the value 4.17647059 to real variable V; it is 


equivalent to these three statements: S? DAK З 3.* x 
70 REM X AND Y NEED TO БЕ INITIALIZED SEPARATELY FOR 
LATER USE 
100 X-7 
110 Үс? 


120 V=33+X/Y 
which could be written on one line as follows: 
100 X27:Yzv:V-33-X/Y 


Here are assignment statements that perform the Boolean operations given earlier 
in this chapter: 


7O REM THESE EXAMPLES WERE DESCRIBED EARLIER IN THE 
CHAFTER 

100 A= NOT ((3+4)>=4) 

110 B=("AA"="AB") OR ((S#2)=(4 ^ 2)) 


The following example shows how a string variable could have its value 
assigned using string concatenation in Applesoft: 


70 REM R$(4) IS ASSIGNED THE VALUE MR. ALTON 
100 МК% "MR. " 
110 М5% "MS. " 
120 N$ = "ALTON" 
200 R$(4) = МКФ + N$ 


DATA and READ Statements 


When a number of variables need data assignments in an Applesoft program, you 
can use the DATA and READ statements rather than the previous type of assign- 
ment statement. Consider the following example: 

—— 


= REM INITIALIZE ALL FROGRAM VARIABLES 
10 DATA 10. 20,-4, 300 
20 READ A,B,C,0 
The statement on line 10 specifies four numeric data values. These four values 
are assigned to four numeric variables by the statement on line 20. After the 
statements on lines 10 and 20 have been executed, А-10, В-20, C=—4, апа 
D=300. 
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If you have one or more DATA statements in your program, then you can 
visualize them as building a column of values. For example, a DATA statement 
that contains a list of ten values would build a ten-entry column. Two DATA state- 
ments each specifying five of the ten data entries would build exactly the same 
column. This may be illustrated as follows: 


10DATA 10,20, 30, 40, 50, 60, 70, 80, 90, 100 | 


First column entry —* | 10 

20 

30 

| 40 
50 
60 
70 
80 
90 

100 /+—Last column entry 


10DATA 10, 20, 30, 40,50 | 
20DATA 60, 70, 80, 90, 100 | 


The first READ statement іп the program starts at the first column entry апа 
takes values sequentially, assigning them to variables named in the READ state- 
ment. The sec d subsequent) READ statements take values from the col- 
umn, starting at the point where the previous READ statement left off. This may 
be illustrated as follows: 


10DATA 10, 20, 30, 40, 50, 60, 70, 80, 90, 100} 


: қүт aM 
220 READA, B, C 


340 READ C, D A- A 
: ent ai 2h 


F = 80 
: С = 90 
. mme a 
490 READA, E, F, G 
500 READ B B = 100 


The DATA column can contain both numeric and stri en you 
ass e values to variables usin men ch variable must be the 
same type (string or numeric) as the corresponding value it is assigned. 

Dom ——— n ((—— —————SHÓ с лла 
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RESTORE Statement 


Youc ing of the DATA column 
by executing a RESTORE statement in Applesoft. Here is how RESTORE works: 


10DATA 10, 20, 30, 40, 50, 60, 70, 80, 90, 100} 


; ———— C 50 
340 READ C, D 
350 RESTORE 


: i m 
490 READ A, E, F, G 
500 НЕАОВ-.--------В-50 


Clearing Variables 


th Integer BASIC and Applesoft let you set every numeric variable and array ele- 
to zero, and every string variable and array element to null, all at once 


e CLR command does this in Integer BASIC. You can use it only in immediate 


mode. Here is an example: 
>Х=37 


SPRINT X 
37 


2CLR 


>PRINT X 
о 


The CLEAR statement does this in Applesoft. It also resets the DATA column 
pointer like RESTORE does. Here is an example: 


110 REM INITIALIZE VARIABLES 
120 X237 

130 A$z"PIG IRON" 

140 PRINT AS 

150 CLEAR 

160 PRINT X 

IRUN 


PIG IRON 
Q 
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DECLARING ARRAY AND STRING SIZE 


If you plan to use arrays or string variables in your program, you need to declare 
тарих ип aoa (er danandnas ТТ йог oF vienes aded 
dimension statements) at the beginning of the program. A dimension statement 
can provide dimensions for any number of arrays and string variables as long as 

n Integer BASIC, you do this by stating the array or string variable name and 

, then specifying its maximum size, enclosed in parentheses. Only one-dimensional 
numeric arrays are allowed — no string arrays o iple-dimensi s. 


The following example dimensions two strings of 5 and 25 characters respec- 
tively, and a numeric array of 13 elements (O through 12): 


10 DIM 51%(5).52%(22).МВ(12) 


Тһе number i tring variable name in a DIM statement is the max- 


imum length that string can be during the program. The number following a 


numeric array name is equal to the largest index value that you can use for that 
array. 
i i rs rr it checks to see if you have 


dimensioned i imensions the array with indexes O 


«through 10 for each dimension used. So you need not dimension an array unless 
you want more than 11 indexes in any one dimension. The following example 
dimensions the single indexed array R$. It also dimensions an integer array of 21 


elements. 


1195 DIM R$(10);RAXC20) 


The double-dimension hotel guest list variable from our earlier example of 
arrays w dimensioned as follows: 


115 DIM Н%(8,10) 


Тһе number (ог numbers) following ап array name іп а DIM statement is equal 
to argest index value that can occur in th j і ition. But 


mber that indexes begin at O. Therefore R$(10) dimensions the variable R$() 


to have 11 values, not 10, since indexes O, 1, 2, 3, 4, 5 8, 9, and 10 will be 
allowed. H$(8,10), likewise, specifies a doubl 9 Gx). 
entries, since the first dimension can have values O, 1, 2, 3, etc., while the second А Ж” E 


imension can es O through 10. ч (5, 2) 


Redimensioning Arrays 


О imensioned an array variable you cannot redimension it without 
rerunning the whole program. Subsequent references cannot use an index higher 
than the number of indexes you declared; each index must have a value between 


O and the number of indexes dimensioned. 
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BRANCH STATEMENTS 


Statements within a BASIC program are nor i i of 
line numbers. This execution sequence was explained earlier in this chapter when 
we described line numbers. Branch statements change this execution sequence. 

тт 


GOTO Statement 
СОТО is the simplest branch statement; it allo i ment 
e executed next. Consider the following example: 
20 А=4 
30 GOTO 100 


The statement on line 20 is an assignment statement; it assigns a value to varia- 
ble A. The next statement is a GOTO; it specifies that program execution must 
branch to line 100. Therefore the instruction execution sequence surrounding this 
part of the program will be: line 20, then line 30, then line 100. 

Of course, some other statement must branch back to line 40, otherwise the 
statement on line 40 would never be executed by program logic as illustrated 
Оо —X———————— 

“ You can branch to any line number, even if the line has nothing but a remark on 
it. However, the computer ignores the remark, so the effect is the same as branch- 
ing to the next line. For example, consider the following branch: 


20 Az4 
30 GOTO 70 


70 REM THIS LINE CONTAINS ONLY A REMARK 


Program execution branches from line 30 to line 70; there is nothing but a 
remark on line 70, therefore the computer moves on to line 80, executing state- 
ments on this line. Therefore, even though you can branch to a remark, you might 
as well branch to the next line. This may be illustrated as follows. 
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d А-4 
30^ GOTO 80 


70 REM THIS LINE CONTAINS ONLY A REMARK 


Attempting to branch to a nonexistent line number causes an error message. 


Computed GOTO Statement <,, 4, ^L&be57 (peur 
63е Pae- = 


There is also a kind of СОТО statement that lets program logic branch t e of 
two or more different line numbers, depending on the current value of a numeric 
expression. 

Consider the Integer BASIC statement sequence: 

10 

20) 

30) A=B-3 

40» GOTO 30*A + 50 


The statement on line 40 is a computed GOTO. When this statement is 
executed, program logic will branch to the statement number computed-by 
evaluating the expression. In this example it branches to statement 50 if variable 
A=0, to statement 80 if A21, while A=2 causes a branch to statement 1 10. If 
the computed line number does not exist in the program a жжж BAD BRANCH ERR 
message results. Notice that variable A is assigned a value in statement 30. The 
Value assigned to A depends on the current value of variable B. The illustration 


does not show how variable B is computed; however, so long as B has a value of 
3, 4, or 5, the statement on line 4O will cause a branch to occur. 


To test the computed GOTO statement in Integer BASIC, key in the following 
program: 


>% REM INITIALIZE VARIARLE B 
210 B= 4 

270 PRINT Б 

230 A=B- З 
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>40 GOTO 320 3 A + SÒ 
749 REM B= З 
250 END 

27?» REM B= 4 
2S0 РКІМТ E 

2270 B= 9 

2100 GOTO 20 
7107 REM B= 5 
2110  FRINT RE 
2120 B= 3 

21230 бт 20 


Now execute this program by typing RUN. 

Can you account for the sequence in which digits are displayed? Try re- 
writing the program so that each number is displayed once, in the sequence: 

5345345... 


^ Applesoft has a slightly different version of the computed GOTO statement, as 
shown below. 


A% = 1 4,10 
= 
30) A96 = B% — 2 


40^ ONA% GOTO 10, 70, 150 
50 


The statement on line 4O is the Applesoft form of computed GOTO. When this 
statement is executed, program logic will branch to statement 10 if variable 
A%=0, to statement 70 i i A= i %=3 causes a branch to state- 

statement 50. 


The expression in an Applesoft computed GOTO statement is evaluated and its 
value determines which line number to branch to from the computed GOTO list of 
line numbers. If the value is 1 the first line number is used, if the value is 2 the sec- 
ond line number is used, and so on. If the value is O, or exceeds the number of line 
numbers in the list, the program falls through to the statement immediately 
following the computed GOTO statement. 
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The following Applesoft program demonstrates how the computed GOTO 


statement works. 
10 BZ = 4 
20 PRINT В” 
зо AZ = BZ - 2 
40 ON AZ GOTO 10,70,150 
70 PRINT BZ 
80 By = 5 
ФО GOTO 30 
150 PRINT В” 
140 BZ = 3 
170 бота 20 


LOOPS 


GOTO and computed GOTO statements let you create any sequence of statement 
execution that your program logic may require. But suppose you want to reex- 
ecute an instruction (or a group of instructions) many times. For example, suppose 
array variable A(I) has 100 elements and each element needs to be assigned a 
value ranging from O to 99. Writing 100 assignment statements would be very 
tedious. It is far simpler to reexecute one statement 100 times in a loop. 


FOR and NEXT Statements 
You can create a loop using the FOR and NEXT statements as follows: 


10 DIM A(99) 

20 FOR I=0 TO 99 STEP 1 
30 ACI)=I 

40 NEXT I 


Statement(s) between FOR and NEXT are executed repeatedly. In this case a 
single assignment statement appears between FOR and NEXT; therefore this 
single statement is reexecuted repeatedly. This kind of program structure is called 
a FOR-NEXT loop. 

So you can see the workings of FOR-NEXT loops, the following program dis- 
plays the values it assigns to array A() within the loop. 


10 DIM А(99) 

20 FOR І=0 TO 99 STEP 1 
ЗО ACT)=I 

39 PRINT ACT) 

40 NEXT I 

30 END 


When you key in RUN, the program displays 100 numbers, starting at O and end- 
ing at 99. 

Statements between FOR and NEXT are reexecuted the number of times 
specified by the /ndex variable appearing directly after FOR; in the illustration 
above this index variable is |. | is specified as going from O to 99 in steps of 1. 
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Variable І also appears in the assignment statement on line 30. Therefore the first 
time the assignment statement is executed, | will equal O and the assignment 
statement will be executed as follows: 


30 А(0) =0 


lis increased by the step size, which is specified on line 20 as 1; | therefore equals 
1 the second time the assignment statement on line 30 is executed. The assign- 
ment statement has effectively become: 


30 A(1)=1 


| continues to be incremented by the specified step until the maximum value of 
99 is reached (or exceeded). 

The step does not have to be 1; it can have any integer value. Change the step 
to 5 on line 20 and reexecute the program. Now the assignment statement is 
executed just 20 times, since incrementing | 19 times by 5 will take it to 95; the 
20th increment will take it to 100, which is more than the maximum value of 99. 
Keeping the step at 5, we could allow the assignment statement to be executed 
100 times by increasing the maximum value of | to 500. Can you make this 
change? (Remember to change the DIM statement as well.) 

The step size does not have to be positive. But if the step size is negative, then 
the initial value of | must be larger than the final value of |. For example, if the step 
size is -1 and we want to initialize 100 elements of A(I) with values ranging from 
0 to 99, then we would have to rewrite the statement on line 20 as follows: 


10 DIM А(9У) 
20 FOR 1=99 TO 0 STEP -i 
30 ACI)=I 
Зе PRINT ACI) 
40 NEXT I 
ШО END 
Execute this program to test the negative step. 
If the step size is 1 (and this is frequently the case), you do not have to specify 
a step size definition. In the absence of any definition, BASIC assumes a step size 
of 1. | 
You may specify the initial апа final index values and the step size using 
expressions if you wish. But you should avoid doing so, since this unnecessarily 
complicates the program. If you must calculate one of these values, it is more effi- 
cient to do so in a separate statement ahead of the loop. 
You can use real values for the initial and final index values and for the step size 
in Applesoft. You do not need to specify the index variable in the NEXT statement 
in Applesoft. But if you do, it will make your program easier to read. 


Nested Loops 


The FOR-NEXT structure is referred to as a program loop since statement execu- 
tion loops around from FOR to NEXT, and back to FOR. This loop structure is very 
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common; almost every BASIC program that you write will include one or more 
such loops. Loops are so common that they are frequently nested one inside the 
other like a set of mixing bowls. There can be any number of statements between 
FOR and NEXT. Frequently there are tens, or even hundreds of statements. And 
within these tens or hundreds of statements additional loops may occur. The 
following illustration shows a single level of nesting: 


10 DIM А(99) 

20 FOR I=0 TG 99 STEP 1 

30 А(19-1 

40 REM DISPLAY ALL VALUES OF ACI) ASSIGNED THUS FAR 
50 FOR J=0 TO I 

60 PRINT A(.) 

70 NEXT J 

30 NEXT I 

90 END 


Complex loop structures appear frequently, even in relatively short programs. 
Here is an example, showing the FOR and NEXT statements, but none of the inter- 
mediate statements: 


50 FOR Iz1 TO 10 
60 FOR X225 TO 347 STEP 


100 FOR А-9 TO O STEP -1 


у 


140 МЕХТ А 
200 FOR B-25 TO 100 STEP 


л 


280 NEXT B 
300 NEXT X 


200 FOR Y=1 TO 20 STEP 2 


600 FOR Р=10 TO 20 


450 NEXT Р 
700 NEXT Y 


1000 FOR Z=1 TO 10 


1090 NEXT 7 


1200 NEXT I 


е 
• 
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The outermost loop uses index variable |; it contains three nested loops that use 
indexes X, Y, and Z. The X-loop contains two additional loops which use indexes 
A and B. The Y-loop contains one nested loop using index P. The Z-loop contains 
no nested loops. 

Loop structures are very easy to visualize and use. There is only one common 
error which you must avoid: do not terminate an outer loop before you terminate 
an inner loop. For example, the following loop structure is illegal: 


SO FOR I=1 TO 10 
60 FOR X225 TO 347 STEP 2 


100 NEXT I 


200 NEXT X 


Every very program must have the same number of FOR and NEXT statements must have the same number of FOR and NEXT statements, 
since every loop must begin with a FOR statement and end with a e every loop must begin with a FOR statement and end with a NEXT state- 
ment. 

For example, suppose there is one FOR statement, but two NEXT statements. 
The first NEXT statement terminates a FOR statement so the loop will execute 


correctly. But the second NEXT statement has no FOR statement, which causes 


an error. 


If you do not include the index variable i in the NEXT statement in an Applesoft 
ro ram, th i s correctly, since 


snepuntersd " you do not believe this, оок: адаіп at ihe complex example illus- 
trated previously. Then work out some additional complex examples. 


SUBROUTINE STATEMENTS 


Once you start writing programs that are more than a few statements long, you 
will quickly find short sections of program that get used repeatedly. For example, 
suppose you have an array variable (such as A()) which is reinitialized frequently 
at different points in your program. Would you simply repeat the three instruc- 
tions that constitute the FOR-NEXT loop that we described earlier? Since there 
are just three instructions, you may as well do so. 

But suppose the loop has ten or eleven instructions that process array data in 
some fashion before it initializes the array. If you had to use this loop many times 
within one program, rewriting the same ten to fifteen statements each time you 
wished to use the loop would take time, but more importantly it would waste a 
lot of computer memory. This concept is illustrated at the top of the following 
page. 

How about separating out the repeated statements and branching to them? 

That is precisely what we will do; the group of statements is then referred to as 


a subroutine. 


——— 
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Start of program — T 


~- Repeated routine 


etc. 


But a problem arises. Branching from your program to the subroutine is simple 
enough; the subroutine has a specific starting line number. But at the end of the 
subroutine, where do you branch back to? 

You can execute a GOTO statement whenever yo i h_to a 

subroutine. This may be illustrated as follows: 


Arbitrarily selected line numbers 
Start of TY 
program —- 10 


100 GOTO 2000 
110 


190 GOTO 2000 ТЕЕ Бер 
200 шы 
: 2000 


н — Start 
250 СОТО 2000 
260 


2150 --Епа 


480 GOTO 2000 
500 


Return 
etc. where? 
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But at the end of the subroutine, where do you return to? If two or more GOTO 
statements branch to the subroutine, there are two or more different places to 
which you will wish to return after the subroutine has completed execution. The 
solution is to use special subroutine statements. Instead of branching to the 
subroutine using a GOTO, use a GOSUB statement. 


GOSUB Statement 


This statement branches in the same way as a GOTO, but in addition it remem- 
bers where to return to. In computer jargon, we say G calls a subroutine. 
= ааа ы ын ыры ш =з ee eee АЙ 


This may be illustrated as follows: 


Subroutine 
2000 Start 
Remember 
100 GOSUB 2000 110 
110 
Go to 2150 RETURN -— End 


remembered 
line number 


End the subroutine with a REL statement. This statement causes a branch 
back to the statement follow 
statement on the line, the program 
e three-statement loop which initializes array A(), if it were converted into a 
subroutine, would appear as follows: 


10 REM MAIN PROGRAM 
20 REM YOU CAN DIMENSION А SUBROUTINE’S 
30 REM VARIABLE IN THE MAIN PROGRAM. 
40 REM IT ІС А GOOD IDEA TO DIMENSION ALL 
So REM VARIABLES AT THE START ОҒ THE MAIN PROGRAM 
Фо DIM А(99) 
70 GOSUB 2000 
80 REM DISPLALY SOMETHING TO PROVE THE RETURN OCCURRED 
"O PRINT "RETURNED" 
100 ENE 
200 NEXT I 
2000 REM SUBROUTINE 
2010 FOR I=0 TO 99 
2020 ACI)=I 
2030 PRINT ACI) 
2040 NEXT I 
2050 RETURN 
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POP Statement 


Under some circumstances you will not want a subroutine to return to the state- 
ment following the GOSUB statement. You might be tempted to just use a GOTO 
ent to return, but that can i ill remem- 


bering where it should return to. In cases like this, use the POP statement. Other- 
wise you ri unuse TURN statements. 


All POP does is make BASIC forget the most recent return location. You can then 
us somewhere else in the program. 
Bypas i i ssiv to enable 


GOTO branching out of subroutines leads to tangled, confusing programs. 


Nested Subroutines 


Subroutines can be nested. That i broutine can itself call er 


subroutine, which in turn can call a third subrouti nd so on. You do not have to 
subroutine using a GOSUB statement and end the subroutine with a RETURN 
statement. BASIC will remember the correct line number for each nested return. 


The following program illustrates nested subroutines: 


10 REM MAIN PROGRAM 
20 REM YOU CAN DIMENSION A SUBROUTINE“ 
30 REM VARIABLE IN THE MAIN FROGRAM. 
40 REM IT IS A GOOD IDEA TO DIMENSION ALL 
50 REM VARIABLES AT THE START OF THE MAIN PROGRAM 
60 DIM ACY?) 
70 GOSUB 2000 
ЗО REM DISPLAY SOMETHING TO PROVE THE RETURN OCCURRED 
?O PRINT "RETURNED" 
100 END 
2000 REM FIRST LEVEL SUBROUTINE 
2010 FOR І-о TO 99 
2020 A(I)=I 
2030 GOSUB 3000 
2040 NEXT I 
2050 RETURN 
3000 REM NESTED SUBROUTINE 
3010 PRINT ACT) 
3020 RETURN 


and puts it into a nested subroutine at line 3000. Nothing else changes. 
While it is erfecty acceptable and even desirable for one subroutine to call 
subroutine-which in turn calls the frst subroutine. This is called recursion, and i is 


жюк а BASIE on Te Арш 


1 This program moves the PRINT А(1) statement out of the subroutine at line 2000 
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Computed GOSUB Statement 


GOTO and GOSUB statement logic is very similar. The only difference is t that 
GOSUB remembers the next line number. It will therefore not come as any 
surprise that there is а computed GOSUB statement akin to the computed GOTO 
statement. The computed GOSUB statement allows you to branch to one of two 
or more subroutines depending on the value of a numeric expression. The com- 
puted GOSUB statement remembers where to return to. It does not matter which 


of the subroutines gets called, the called subroutine's RETURN statement will 


cause a br ack to the remembered line number. 


You can nest subroutines using computed GOSUB me j ou can 
nest subroutines using standard GOSUB statements. 


Consi ing Integer BASIC statement: 
2100 GOSUB AxSOO-2000 
2110 REM 
The expression on li i i tement is 


ogic branches to the subroutine at the line number computed 


by evaluating the expression. In this example, it branches to statement 2000 if 
А-0, to statement 2500 if Az 1, and so on. If the computed line number does not 
exist in the program a BAD BRANCH ERR message results. 

The Applesoft version of the computed GOSUB statement works in a manner 


similar to the Applesoft computed GOTO statement. Here is an example: 


i. ы ы сы Бе а ен: 
190 


1100 ON А GOSUB 1000,500, 5000, 2300 


1110 КЕМ 


үсеп the. statement on line 100 is executed, if A=1 the subroutine beginning 
at Ji au A- 2 the subroutine beginning at line 5 =3 


the "m О is called. If A24 t inning at 
line 2300 is called. If A has any value other than 1 tion 
falls through to line 110 (no subroutine is called). 
—————————— 


CONDITIONAL EXECUTION 


The computed GOTO and computed GOSUB are conditional statements. That is, 
the exact flow of program execution depends on the values of one or more varia- 
bles which can change as the program is running. The exact program flow 
depends on the condition of the variables. 


IF-THEN Statements 


Another conditional statement is the IF-THEN statement. It has the general form: 
————M—À—M——————————— 


IF expression TH atement 


ыла ---------- 
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If the expression is true, then the statement is executed. Relational and Boolean 


expressions are most common with IF-THEN statements, but arithmetic expres- 
sions can be used as well. This gives a BASIC program real decision-making 
capabilities. Here are three simple examples of IF- THEN statements: 


10 IF A=B+5 THEN PRINT MSGS 
40 IF CC$-"M" THEN IN-O 
50 IF 0<14 AND М<М1 THEN GOTO 66 


The statement on line 10 causes a PRINT statement to be executed if the value 
of variable A is five more than the value of variable B. The PRINT statement will 
not be executed otherwise. 

The statement on line 40 sets numeric variable IN to O if string variable CC$ is 
the letter M. 

The statement on line 5O causes program execution to branch to line 66 if 
variable О is less than 14, and variable M is less than variable M1. Otherwise рго- 
gram execution will continue with the statement on the next line. 

If you do not understand the evaluation of expressions following IF, then refer 
to the discussion of expressions given earlier in this chapter. 


X An JE-THEN statement can be followed by other statements оп the same pro- 
gram line. Integer BASIC and Applesoft handle this situation somewhat 
differently. 
In Integer BASIC, only the statement which immediately follows THEN is condi- 
Жау ласина Any рас анаи, опе ааа pengram Ша ace ahis 


executed atter whe ion i - N statement is true or 
false. This may be illustrated as follows: 


10 IF V>100 THEN PRINT "DEWEY WINS": GOSUR 2000 
20 T=T+V: PRINT Т 


In the example above, the program will only print the message DEWEY WINS if 
the value of variable V is greater than 100. The program will call the subroutine at 
line 2000 no matter what the value of V is. 

4. Applesoft executes statements that follow an ІҒ-ТНЕМ statement on the same 
ine only if the expression in the IF-THEN statement is true. If the expression is 
fal gram execution drops d he fi nt on m 
line. In the example above, the program will print the message DEWEY WINS and 
call the subroutine at line 2000 only if the value of variable V is greater than 100. 


If V is less than or equal to 100, the program will not print the message or call the 
subroutine, but will instead proceed directly to the first statement on line 20. 


There is a special form of the IF-THEN statement available in Applesoft. 
Whenever the conditionally executed statement is a GOTO state t, you can 
omit the word THEN if you wish. The following two statements are equivalent: 


110 IF MM$-DD$ THEN GOTO 100 


is the same as: 


110 IF MM$-n0iD$ GOTO 100 
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INPUT AND OUTPUT STATEMENTS 


There are a variety of BASIC statements that control the transfer of data to and 
from the computer. Collectively these are referred to as /nput/output statements. 
The simplest input/output statements control data input from the keyboard and 
data output to the display screen. We are going to discuss these simple input/out- 
put statements in the paragraphs that follow. But there are also more complex 
input/output statements that control data transfer between the computer and pe- 
ripheral devices such as cassette recorder, disk drives, and printers. These more 
complex input/output statements are described in Chapters 4 and 5. Chapter 6 
covers output statements to the display screen for graphics. 

We have already encountered the PRINT statement, which outputs data to the 
display screen. So let's discuss this statement first, before looking at input state- 
ments. 


PRINT Statement 


Why use PRINT instead of DISPLAY or some abbreviation of the word display? 
The answer is that in the early sixties, when the BASIC programming language 
was being created, displays were very expensive and generally unavailable on 
medium or low cost computers. The standard computer terminal had a keyboard 
and a printer. Information was printed where today it is displayed; hence the use 
of the word PRINT to describe a statement which causes a display. 


The PRINT ill disp! t or numbers. For example, the following 


statement will display the single word TEXT: 
10 PRINT "TEXT" 


To displa i after PRINT, 
like this: 
>A=10 


2PRINT 5.4 
5 10 


The statement above displays the number 5, and then the number 10 on the 
same line. 


You can display a mixture of text and/or numbers by listing the information to 
be displayed after PRINT. Use commas to separate individual items. The followin 
followed by the numeral for each number: 

Қіші о еі. Қы ы side uf н ee ee 


10 PRINT "ONE", 1, "TWO", 2, THREE" 3, "FOLIR", 4, "FIVE", 5 
20 END 


If you separate vari i i ve, then the Apple Il auto- 
matically allocates a fixed number of spaces for each variable displayed. Try 
executing the statement illustrated above in immediate mode to prove this to 


yourself. If you want the display to take out empty spaces, separate the variables 


94 APPLE Il USER'S GUIDE 


——using_semicolons, as follows: 
10 PRINT "ONE"; 13 "TWO"3 23 "THREE": 33 "FOLIR" $5 45 "FIVE"35 
20 END 
Again enter this statement in immediate mode to understand how the semicolon 
works. 
A PRINT statement will automatically return the cursor to the left margin and 
drop it down one line as its last action. In computer jargon, this is called a carriage 
return. You_can suppress the carriage return b ing a comma or a semicolon 
after the last value in the PRINT list. A comma occurring after the last value will 
move the cursor to where the next value would be d 3 : 
illustrate this, type in the following three-statement program and run it tby typing 
in RUN: 
10 PRINT "ONE",1,"TWO",2 
20 PRINT "THREE", 3, "FOUR",4 
30 END 


Now add a comma to the end of the statement on line 10 and again execute 
the program by typing RUN. You will see the two lines of display occur on a single 
line. 

Now replace the comma at the end of line 10 with a semicolon and again run 
the program. The display occurs on a single line, but the space between the 
numeral 2 and the word THREE has been removed. By changing other commas to 
semicolons you can selectively remove additional spaces. 


We have been displaying the numerals by inserting them directly into the 
PRINT statement. You can if you wish display the contents of variables instead. 


does the same thin t t PRINT statement example, 


but uses array A() to create digits. Try entering this program and running it: 


= DIM ACS) 

10 FOR I-1 TO 5 

20 ACI)=I 

30 NEXT I 

40 PRINT "ONE"3A(1)3"TWO"5A(2)3 " THREE" 5ACS) 5 "FOUR"3A(4)3 
"FIVE":ACS) 

БО END 


In lesoft, you can put the di d move 


the PRINT statement into a FOR-NEXT loo ging the program as follows: 


10 DATA "ONE", "TWO", "THREE" ; "FOUR", "FIVE" 
20 FOR І = 1 TO S 

40 READ М% 

SO PRINT МӨ31: 

60 NEXT I 

70 END 


INPUT Statement 


When an INPUT statement is executed, the computer waits for input from the 
keyboard; until the computer gets the input it requires, nothing else will happen. 
ШЕИНМ ea ee Án ÍÓM B — ——— — iila — 
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Іп its simplest form, an INPUT-stetement-begins-with-the word INPUT and is 
followed by a variable name. Data entered from the keyboard is assigned to the 
named variable. The variable name type determines the type of data which must 

e en i i e satisfied only by numeric input. To 
demonstrate numeric input, key in the following short program and run it (try 
entering some alphabetic data and see what happens): 


10 INFLT А 
20 РКІМТ А 
25 REM END PROGRAM IF © ENTERED 
ЗО IF A = О THEN END 
40 GOT 10 
cuting ап | com r displays a question mark, 


then waits for your entry. The program above displays each key as you press it. In 
computer jargon, the display screen echoes the keyboard. In addition, the number 
is displayed again because of the PRINT statement on line 20. The first display 
occurs when the INPUT statement on line 10 is executed and you make an entry 
at the keyboard. The second display is in response to the PRINT statement on line 
20. 

An INPUT statement can input more than one value at a time. To do this, list all 
the variables you want to input values for following the word INPUT. Separate the 
variables with commas. When such an INPUT statement is executed, you must 
respond with a separate value for each variable. Be sure each value is the same 
type as the variable it will be assigned to. 

When you respond to an INPUT statement, do not use commas as punctuation 
in large numbers; enter 1000 not 1,000. 

The following example inputs two numeric values then displays these inputs. 


INPUT A,B 

PRINT А, Е 

КЕМ END PROGRAM IF О ENTERED 
IF А=0 OR B-O THEN END 

бото zO 


roo o 


~, 
— 


р 


On Bi t hj 


© 


Run the program above and try entering one number followed by а comma, 
after that another number, and then press Return. Now try something a bit 
different. Enter one number and press Return. As you see, the Apple ІІ reminds 
you to enter the next value. So enter another number and press Return. Thus, 
when an INPUT statement calls for more than one numeric value, you have a 
choice of entering all the values on one line or entering them on separate lines. 

The INPUT statement works somewhat differently with string variables in 
Integer BASIC. First of all, it does not display a question mark. Try this example: 


10 DIM А%(19) 

20 INPUT AS 

ЗО PRINT A$ 

35 REM END PROGRAM IF NULL ENTRY 
40 IF АФ-"" THEN END 

со GOTO 20 
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When you run the program above, try entering a string of more than ten 
characters. You will get a +++ STR OVFL ERR message and the program will stop. 
The length of the string you enter cannot exceed the maximum length of the 
string variable used in the INPUT statement. 

Integer BASIC forces you to enter each string value on a separate line. If an 
INPUT statement specifies a list of variables, and there are string variables on the 
list, the associated string values must be entered on separate lines. This is 
because Integer BASIC lets you include commas as part of a string value. You can 
prove this for yourself by running the example program above and entering the 
string value DOE, JOHN. The following example illustrates what happens when a 
string variable is part of an INPUT statement in Integer BASIC. Experiment with 
this program; try to enter all four values on the same line, separated by commas. 
What happens? Try entering each value on a separate line. See what happens if 
you enter a numeric value or a comma as part of a string value. 

10 DIM А%(10).В%(10) 

20 INPUT 4$.4.B$.B 

30 PRINT АФ, А, B$, В 

25 КЕМ END PROGRAM IF NULL ENTRY 
40 IF A$="" THEN END 

50 GOTO 20 

As we discussed earlier, any real variable can have an integer value in 
Applesoft. Therefore you can input an integer value for a real variable. A real value 
entered for an integer variable is converted to an integer value according to the 
truncation rules presented in the ''Mixed-Type Expressions" section of this 
chapter. 


INPUT Statement Prompts 


The INPUT statement is very fussy; its syntax is too demanding for any normal 
human operator. Just imagine some poor office worker who knows nothing about 
programming; on encountering the types of error message which can occur if one 
comma happens to be out of place, he will give up in despair. You are therefore 
likely to spend a lot of time writing “idiot proof” data entry programs. These аге 
programs which are designed to watch out for every type of mistake that an 
operator can make when entering data. Ап idiot proof program will cope with 
errors in a way that the operator can understand. Chapter 4 describes these data 
entry programming techniques in detail. 

One simple trick worth noting, however, is the INPUT statement's ability to dis- 
play a short message that can describe the expected input. Such a message is 
called a prompt message. The message appears in the INPUT statement as a 
string value enclosed in quotation marks. The message will be displayed just 
ahead of the input request. This certainly beats sticking a bunch of variables into a 
single INPUT statement, with only your memory reminding you what to enter next. 

In Integer BASIC, you put the prompt message immediately following the word 
INPUT. It is followed by a comma and then the list of variables. When the list con- 
tains more than one variable, the prompt message is still only displayed once, on 
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the first line of input. If the first variable on the list is numeric, a question mark is 
displayed immediately after the prompt message. If the first variable is a string, no 
such question mark is displayed. Here is an example: 


10 DIM А%(10) 
20 INPUT "ENTER YOUR NAME AND AGE ",А%-А 
30 PRINT A$:"IS": 
Зб REM IF ENTRY IS NULL.» END PROGRAM 
40 IF A$-"" THEN END 
50 GOTO 20 
In Applesoft, you put the prompt message immediately after the word INPUT. It 
is followed by a semicolon which is in turn followed by the variable list. The exis- 
tence of a prompt message suppresses the standard INPUT statement question 
mark. The prompt message is displayed only once, even if more than one line is 
required to enter all of the values requested by the variable list. 
Here is an Applesoft example: 


ZO INPUT "ENTER YOUR NAME AND АСЕ: "АФ, А 
30 PRINT ASS" IS "s 

39 REM IF ENTRY IS NULL. END PROGRAM 

40 IF A$ = "" THEN END 

50 бото 20 


The GET Statement 


The GET statement, available only in Applesoft, inputs a single character from the 
keyboard. It does not display the character on the screen. You do not press RETURN 
after typing the character. The entry is treated as a string value or as a numeric 
value, depending on the type of variable that follows the word GET. Type in the 
following program and run it: 


10 GET A$ 

20 PRINT AS 

25 REM IF ENTRY IS AN E; END PROGRAM 
ЗО IF A$ = "E" THEN END 

40 GOTA 10 


We can make GET wait for a specific character by testing for the character as 
follows: 

10 GET AS 

20 IF A$ < > "X" THEN GOTO 10 

30 PRINT AS 

40 END 


This program waits for the letter X to be entered. Nothing else will do. 

If the GET statement specifies an integer or real variable, then the entry must 
be a numeric digit. Otherwise, the ?SYNTAX ERROR occurs and the program 
stops. Because of this and other problems that can occur when using GET with a 
numeric variable, GET statements usually receive string characters. 

Programs use the GET statement most frequently when generating dialogue 
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with an operator. For example, a program may wait for an operator to prove that 
she or he is there by entering a specific character (e.g., Y for yes). Here is appropri- 
ate program logic: 

10 PRINT "OPERATOR! ARE YOU THERE?" 

15 PRINT "TYPE Y FOR YES" 

20 GET А% 

30 IF A$ < > "Y" THEN GOTO 20 

40 PRINT "ОК, LETS GET ON WITH IT" 

50 END 
Notice that this sequence never displays the character entered at the keyboard. 
Try rewriting the program so that any character entered for the GET statement is 
displayed. 


HALTING AND RESUMING 
PROGRAM EXECUTION 


If a program is running and you want to stop it, press Ств. and C concurrently. If 
the program is waiting for keyboard input from an INPUT statement when you 
type CrRL.-C, you will also have to press Return after you press CrRL-C. 

In Integer BASIC, you will see the message STOPPED AT and then the line 
number at which program execution halted. You can resume program execution 
by typing the command CON. 

In Applesoft, you will see the message BREAK IN followed by the line number 
at which program execution halted when you pressed Crrt-C. You can continue 
program execution by typing CONT. 


The Reser Key 


You can of course interrupt your program at any time by pressing the Reset key 
(on some versions of the Apple Il, you must press Crn.-Reser). 

On the Apple Il Plus and on an Apple Il with the Language System installed, 
Reset has the same effect as Ста!-С. 

On versions of the Apple ll without the Autostart Monitor, pressing Reset 
causes the Monitor prompt (ж) to appear. If you were using Integer BASIC or Firm- 
ware Applesoft, type CrRL-C to return to the language you were using. If you were 
using cassette-based Applesoft, type OG to return to Applesoft. If you were using 
disk-based Applesoft, type 3DOG to return to Applesoft. 

If you try to recover incorrectly from an accidental Reset, you will lose your 
BASIC program. 


The END Statement 


The program will halt execution when it encounters an END statement, as we de- 
scribed earlier in this chapter. 

You cannot continue program execution after Integer BASIC executes an END 
statement. 
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The STOP Statement 


Applesoft has another command which will halt program execution when it is 
executed: the STOP command. When Applesoft executes a STOP command, it 
displays the message BREAK IN along with the line number it stopped at. 

You can continue program execution in Applesoft after either the END or STOP 
command by typing CONT. 


The WAIT Statement 


Applesoft has a command which allows you to specify a pause in program execu- 
tion. The WAIT statement causes program execution to halt until a memory loca- 
tion (which you specify) has a value which you specify. You can, for example, 
make your program pause until someone presses the button on game control 
number 1. Here is how: 


10 REM -WAIT FOR BUTTON ON GAME CONTROLLER МО.1 
20 PRINT "PRESS BUTTON ON GAME CONTROLLER ONE" 


30 WAIT - 16236,128 
40 PRINT "BANG!" 
So END 


See Chapter 8 for more complete details on the WAIT statement. 


FUNCTIONS 


Another element of BASIC is the function, which in some ways looks like a varia- 
ble, but in other ways acts more like a BASIC statement. 

Perhaps the simplest way of understanding what a function is is to look at an 
example. In the assignment statement: 


110 A=SUR(B) 


the variable A is set equal to the square root of the variable B. SOR specifies the 
square root function. Here is a string function: 


20 L=LEN(DS) 


In this example the string variable L is set equal to the length of string variable D$. 

Functions can substitute for variables or constants anywhere in a BASIC state- 
ment, except to the left of an equal sign. In other words, you can say that 
А-5ОВН (В), but you cannot say that SOR(A) -B. 

The discussion which follows shows you how to use functions. An incomplete 
summary of the functions available in Integer BASIC and Applesoft is presented 
here but a complete description of all functions is given in Chapter 8. Many func- 
tions are not available in Integer BASIC. We will note those that are not. 

You specify a function using the appropriate reserved word (such as SQR for 
square root), followed by an argument or arguments enclosed in parentheses. In 
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the case of A=SQR(B), SOR requires a single argument, which in this instance is 

the value to take the square root of. For L=LEN(D$), LEN specifies the function; 

the argument D$, enclosed in parentheses, is the string to take the length of. 
Generally stated, any function will have one of these two formats: 


Single argument for a 
function that has just 
one argument 


function(arg1) 
function(arg1,arg2) 


el 


Los arguments for a 


function that needs 
two arguments 


Reserved word that specifies 
the function 


A few functions need three arguments. Each function argument can be a cons- 
tant, a variable, or an expression. 

Each and every function in a BASIC statement is reduced to a single numeric or 
string value before any other parts of the BASIC statement are evaluated. First, 
the function argument is evaluated according to the rules we set down earlier. 
Once it is reduced to a numeric or string value, the function is applied to it, yielding 
another numeric or string value. Not until all functions in a given expression are 
evaluated in this way is the expression itself evaluated. For example, in the follow- 
ing statement: 

110 Bz24.74SR(GC)*5)-SIN(CO., Z*D) 


SQR and SIN functions are evaluated first. Suppose SQR(C)26.72 and 
SIN(0.2--D) 20.625. The expression on line 10 will first be reduced to: 


24.7%(6.72 + 5) – 0.625) 


then this simpler expression is evaluated. 


NUMERIC FUNCTIONS 


Here is a list of the numeric functions that you can use with both Integer BASIC 
and Applesoft: 


SGN Returns the sign of an argument: +1 for a positive argument, 
-1 for a negative argument, O for a zero argument. 
ABS Returns the absolute value of an argument. A positive 


argument does not change; a negative argument is 
converted to its positive equivalent. 
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RND Generates a random number. See Chapter 8 for more 
details. 


Here is a list of the numeric functions that you can use with Applesoft only: 


INT Converts a floating point argument to its integer 
equivalent. 
—b SQR Computes the square root of the argument. 
~~ EXP Raises the constant e to the power of the argument 
(е). 
LOG Returns the natural logarithm of the argument. 
SIN Returns the trigonometric sine of the argument, which is 
treated as a radian quantity. 
COS Returns the trigonometric cosine of the argument, 
which is treated as a radian quantity. 
TAN Returns the trigonometric tangent of the argument, 
which is treated as a radian quantity. 
ATN Returns the trigonometric arctangent of the argument, 


which is treated as a radian quantity. 


Using Numeric Functions 


You should start using functions as soon as possible, but do not bother with func- 
tions you do not already understand. For example, if you do not understand trig- 
onometry, you are unlikely to use SIN, COS and TAN functions in your programs, 
and there is not much point learning what they are. 
Here is an example that uses a numeric function: 

10 А--234 

20 B= SGN (A) 

30 PRINT B 

40 END 


When you execute this program, the result displayed is —1, since the —234 is 
negative. As an exercise, change the statement on line 10 to an INPUT. Change 
line 40 to GOTO 10. Now you can enter a variety of values for A and watch the 
SGN function at work. 

Here is a more complex example using Applesoft BASIC numeric functions: 


10 INFUT A,B 

20 IF LoG (A) < О THEN А = 1 / А 
30 PRINT SOR (А) * EXP (B) 

37» REM USE CTRL-C TO END FROGRAM 
40 GoTo 10 


If you understand logarithms, then as an exercise change the statement on line 
20, replacing the LOG function with some other numeric function. 
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| X STRING FUNCTIONS 


String functions allow you to manipulate string data in a variety of ways. You may 
not need to use numeric functions that you do not understand, but you must make 
an effort to learn every string function. 

Here is a list of the string functions that you can use with both Integer BASIC 
and Applesoft: 


ASC Converts a string character to a standard numeric code 
(ASCII) equivalent. 

LEN Returns the number of characters contained in a text 
string. 


Here are the string functions you can use in Applesoft only: 


STR$ Converts a numeric value to a string of text characters. 

VAL Converts a string of text characters to their equivalent 
number (if such a conversion is possible). 

CHR$ Converts a numeric (ASCII) code to its equivalent text 
character. 

LEFT$ Extracts the left part of a text string. Function arguments 
identify the string and the desired left part. 

RIGHT$ Extracts the right part of a text string. Function 
arguments identify the string and the desired right 
part. 

MID$ Extracts the middle section of a text string. Function 
arguments identify the string and the required mid 
part. 


String functions let you determine the length of a string, extract portions of a 
string, and convert numeric values, numeric (ASCII) codes, and string characters. 
These functions take one, two, or three arguments. Here are some examples: 

STR$(14) Converts 14 to “14”. 

LEN("ABC") Returns the length of the string. The number 3 is 
returned since the string has three characters. 

LEN(A$+B$) ^ Returns the combined length of the two strings. 

LEFT$(ST$,1) Returns the leftmost character of the string ST$. 


Integer BASIC Substrings 


Although Integer BASIC has no functions that let you extract portions of a string, 
there is a way of doing it. You specify the starting position and the number of 
characters in the substring, as in the following example: 


10 DIM AS$(20),BS (5) 
20 BS=AG( 1,4) 
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In the example above, В% is set equal to the first four characters of A$. It may look 
to you as though B$ is being assigned the value of one of the elements of string 
array А%(), but remember that Integer BASIC does not allow string arrays, much 
less double-dimension string arrays. Instead, this notation refers to a substring. 
The first value in parentheses is the starting position of the substring, and the sec- 
ond value is the number of characters in the substring. 


Integer BASIC String Concatenation 


The LEN function allows you to concatenate strings in Integer BASIC. Here is an 
example: 


10 DIM A$CIO), B$C10) , C$ (10) 
20  A$-"WIND" 

30 B$-"PIPE" 

40 C$="LINE" 

50 А%( LEN(A$) *1)-B$ 

&0 PRINT 4% 

70 B$( LEN(B$)*1)-C$ 

80 PRINT B$ 

90 END 


2RUN 
WINDPIPE 
PIPELINE 


SYSTEM FUNCTIONS 


In the interest of completeness, system functions are listed below. They perform 
operations which you are unlikely to need until you are an experienced pro- 
grammer. 

Here is a list of system functions available: 


PEEK Fetches the contents of a memory location. 


FRE Returns available free space — the number of unused 
read/write memory bytes. Not available in Integer BASIC. 
USR Transfers to an assembly language program. Not 


available in Integer BASIC. 


USER-DEFINED FUNCTIONS 


In addition to the many functions which are a standard part of BASIC, you can 
define your own arithmetic functions in Applesoft, providing they are not very 
complicated. User-defined string functions are not allowed. A DEF FN statement 
defines the function. You invoke the function with an FN statement. Here is a 
short program that uses a DEF FN statement: 


10 DEF FN P(X) = 100 * X 
20 INPUT A 
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ЗО PRINT А, FN P(A) 
35 REM USE CTRL-C TO END PROGRAM 
40 GOTO 20 


The function identifier follows the reserved word FN. Rules for naming the 
identifier are the same as rules for real variable names. In the example we use P, 
therefore the function name becomes FNP. If the identifier were AB, then the 
function name would be FNAB. 

The arithmetic expression on the righthand side of the equal sign defines the 
function. When you invoke the function with the FN statement, the expression is 
evaluated (using the current values for any variables mentioned in the expression). 
The resulting numeric value is treated the same as any numeric value would be in 
the context where the FN statement appears. 

In the DEF FN statement, a single variable must follow the function identifier, 
and must be enclosed in parentheses. This variable name is /oca/ to the function 
definition; it has no effect outside of the DEF FN statement. You can use the same 
variable name elsewhere in the program without affecting the function, and the 
variable in the function will not affect any like-named variable elsewhere in the 
program. 

In use, the FN statement must be followed by the function identifier, which 
must be followed by a numeric constant, variable, or expression enclosed in 
parentheses. When Applesoft encounters the FN statement, it assigns the value 
of the constant, variable, or expression to the local variable in the DEF FN state- 
ment. (The value of a variable outside the DEF FN statement which has the same 
name as the local variable is unchanged.) If the local variable appears in the func- 
tion-defining expression, Applesoft uses its recently assigned value when evaluat- 
ing the expression. 


FUNCTION NESTING 


The argument of a function can be an expression; the expression may contain 
functions. In other words, functions can be nested. Here is an example: 


10 INPUT А 

20 PRINT SGN ( ABS (A)) 

25 REM USE CTRL-C TO END THE PROGRAM 
30 GOTO 10 

40 END 


Try experimenting by creating immediate mode PRINT statements that make 
complex use of numeric and string functions. 


4 


Advanced BASIC Programming 


This chapter carries on from Chapter 3 in describing how to program the Apple Il 
in BASIC. it covers many new BASIC statements and explores new facets of some 
familiar ones. Chapter 3 taught you enough to let you make your Apple ІІ do some 
fancy tricks; this chapter shows you how to make it a really useful tool. 


DIRECT ACCESS AND CONTROL 


There аге a number of statements which allow you direct access to the Apple Il. 
There are many things you can do only via these statements — things like sensing 
the game controls, operating the speaker, and making full use of peripheral 
devices. 


MEMORY AND ADDRESSING 


The Apple Il can have up to 65,536 individually addressable memory locations, 
each of which can store a number ranging between O and 255. (This strange 
upper bound is in fact 29.) All programs and data are converted into sequences of 
numbers which are stored in this fashion. 

You must specify a memory location for each of the following BASIC state- 
ments. You can specify the address with a number, a variable, or an expresion. In 
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any case, it must evaluate to a valid memory location. There are two valid 
addresses for each memory location. One is positive and is an integer between O 
and 65535. The other is negative and can be derived by subtracting 65536 from 
the positive address. For example, —32767 and 32768 address the same 
memory location. Another memory location is addressed by either —1 or 65535. 

When you remember that the largest number allowed in Integer BASIC is 
32767, you can see the utility of using negative numbers for addressing the 
higher memory locations. 

If you specify a memory location in Applesoft with a real value, it will be con- 
verted to an integer value for use as an address. 


PEEK and POKE 


The PEEK function lets you read the value stored in any Apple ІІ memory location. 
Consider the following statement: 
10 А = РЕЕК(200) 
This statement assigns the content of memory location 200 to variable А. 
The POKE statement puts a value into a memory location. For example the 


statement: 20 POKE 8000.4 

takes the value of variable А and stores it in memory location 8000. The value to 
be written into memory may be a number, a variable, or an expression with a value 
between O and 255. 

You can PEEK into read/write memory or read-only memory (RAM or ROM). 
But you can POKE only into read/write memory. This is self-evident; read-only 
memory, as its name implies, can have its contents read, but cannot be written 
into. 


CALL Statement 


You can transfer control from BASIC to an assembly language program or 
subroutine with the CALL instruction. Look at this sample CALL statement: 

100 CALL А1 
Control transfers to the memory location specified by variable A1. 

The assembly language subroutine or program can be one that is constantly 
resident in the Apple il (in ROM) or it can be one you provide. The Monitor has an 
intrinsic subroutine that will clear the display screen, for example. Appendix D has 
a complete list of intrinsic subroutines you may find useful. Also, refer to Chapter 
7 for more coverage of the Monitor and assembly language. 


HIMEM: and LOMEM: Statements 


The memory in your Apple ll is used in different ways. Part of it is used to store 
your BASIC program, part for your program variables, another part for programs 
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to manage disk drives (if you are using disk drives), and so on. Some of the 
memory is used for graphics, as we will learn later in Chapter 6. 

The statements HIMEM: and LOMEM: allow you to set aside safe areas of 
memory for assembly language programs and high-resolution graphics. 

Here is an example of each of these statements: 


SO НІМЕМ: 38400 
60 LOMEM: 12291 


The upper and lower boundaries are set automatically by the Apple Il to the high- 
est and lowest memory locations available for a BASIC program on your particular 
Apple Il. You may need to reset these boundaries if you are using high-resolution 
graphics or assembly language programs, which we will cover in Chapters 6 and 
7. For more information on memory uses, see Appendix G. 


USING PERIPHERAL DEVICES 


When you turn the Apple 1 on, it expects input from the keyboard and displays its 
output on the screen. The keyboard is the standard input device and the display 
screen is the standard output device. But as you are no doubt aware, the Apple Il 
can communicate with peripheral input and output devices. These include: 


* A cassette recorder for loading and saving programs (and some data) 
* Disk drives for loading and saving programs and data 

“А printer for permanent paper copies of data and programs 

* A graphics tablet for inputting freehand graphic designs 

• Communications with other computers. 


The cassette recorder plugs into the Apple Il through two special jacks. 

All other input and output devices plug into add-on electronic circuit boards 
which connect to slots inside the main Apple ll computer. These circuit boards are 
called controllers, interface cards, cards, or interfaces. You specify which device 
you want to use by the slot number its controller is connected to. There are eight 
slots, numbered O through 7. The screen display and keyboard are always slot O. 


The PR3t and IN+ Statements 


To select a different output slot use the PR+ statement. For a different input 
source use IN+. The following immediate mode example selects the screen dis- 


play for output: PRHO 


As long as the Disk Operating System (DOS) is not present, you use PR3t and 
IN+ the same way in programmed mode and immediate mode. Using РЕЗ and 
ІМЗЕ in programmed mode with DOS present is a bit more complicated. You must 
use a PRINT statement which prints a CrRL.-D character followed immediately by 
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the PR# ог ІМ command. The following statements direct subsequent PRINT 
statement output to slot 1. Via the interface in this slot, output will go to a printer 
or any other device connected to the card. 


100 L$ = "": КЕМ СТКІ-П 
110 PRINT D$:"PR41": REM SELECT SLOT NUMBER 1 (PRINTER) 


With DOS absent, you would use the following statement instead: 
110 PR#1 : REM SELECT SLOT 1 (PRINTER) 


Notice that PR+ and ІМЗЕ each have a single parameter. It must be a numeric 
value between O and 7. Any other value will cause unpredictable results. If there is 
no interface card in the slot selected by PR or IN+, then the Apple ll locks up; 
your only recourse is to press Reser. 


PROGRAM OUTPUT AND DATA ENTRY 


The most inexperienced programmer quickly discovers that the input and output 
sections of a program are its trickiest parts. 

Nearly every program uses data which must be entered at the keyboard. Will a 
few INPUT statements suffice? In most cases the answer is no. What if the opera- 
tor accidentally presses the wrong key? Or worse, what if the operator discovers 
that he or she input the wrong data — after entering two or three additional data 
items? A usable program must assume that the operator is human, and is likely to 
make any conceivable human error. 

Results, likewise, cannot simply be displayed, or printed, by executing a bunch 
of PRINT statements. A human being will have to read this output. Unless the out- 
put is carefully designed, it will be very difficult to read; in consequence informa- 
tion could be misread, or entirely overlooked. 

Fortunately BASIC on the Apple ll has many capabilities that make it easy to 
program input and output correctly. We will describe some of these capabilities 
before looking specifically at good input and output programming practices. 


MORE ABOUT THE PRINT STATEMENT 


Normally a PRINT statement ends by returning to the beginning of the next display 
line (it performs a carriage return). This causes the next PRINT statement to begin 
displaying in the first character position of the next line. Thus the following pro- 
gram displays a column of 20 W characters in the first character position of 20 


rows: 
>NEW 


2200 Cé="W" 

2210 FOR Ігі TO 20 
2220 PRINT C$ 
2230 NEXT I 
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2240 PRINT "РНЕМ!" 


REL BESS Tle TSS хш хр хш в 


НЕМ! 


sing Semicolons 


earing after any variable i in the PRINT statement parameter list 
causes the next displ vailable character posi- 


presses the carriage return. Therefore the following program will display 800 W 


characters across 20 rows of a 40-column display. 


>МЕМ 


2200 C$z"W" 

2210 FOR Ісі TO 800 
2220 PRINT C$; 

2230 NEXT I 

2240 PRINT "PHEW!" 
2250 END 


>RUN 

WHWWWWWWWWWWWWWWWWWWWWWWWWWWW WW WWW WWW WW 
WWWWWWWWWWWWWWWWWWWWWWWWWWWW WWW WW WWW 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW WWW ld 
WWWWWWWWWWWWWWWWWWWWWWWWWWWW WWW WWW 
WWWWWWWWWWWWWWWWWWWWWWWWW WW WW WWW WWW WWW WW 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW Wild 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW WWW WWW 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW WW 
WWWWWWWWWWWWWWWWWWWWWWWWW WWW WWW WWW 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW WWW Wl 


110 APPLE Il USER'S GUIDE 


WWWWWWWWWWWWWWWWWWWWWWWWWW WWW WWW WWW 
WAWAWWAHWUAWUWAWAWWIAWAWWWIWIHWHAHWWWIWWIAWWWWWWWWWWW 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW 
WWWWWWWWWWWWWWWWWWWWWWWWWWWW WW WWW 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW 
WWWWWWWWWWWWWWWWAWWWWWWWWWWWW WW WWW 
WWWWWWWWWWWWWWWWWWWWWWW WWW WWW WWW WWW 
WWWWWWWWWWWWWWWWWW WWW WWW WWW WWWWW WWW ТАГИ 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW 
PHEW! 


The FOR-NEXT loop index, variable І, is used as a counter to indicate the num- 
ber of W's to be displayed, in this case 800. On the first execution of PRINT, a 
new line is begun and the character W is displayed. The semicolon prevents a 
return to the next line, so the cursor remains at the character position following 
the first W. The second W is then displayed and the cursor is left in the next 
character position. This sequence continues up to the end of the first line, then the 
cursor moves to the beginning of the next line. This sequence continues for 20 
lines (of a 40-column display). 

Why does PHEW! print оп a new line? It doesn't really; it appears to start a new 
line because the last W character is displayed in the last position of the previous 
line. Change the FOR-NEXT loop from 800 to 780 iterations and PHEW! is dis- 
played at the end of the last line of characters. This may be illustrated as follows: 


>200 C$z"W" 

>210 FOR I=1 TO 780 
>220 PRINT C$: 

2230 NEXT I 

2240 PRINT "PHEW!" 
2250 END 


2RUN 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW 
WWWWWWWWWWWWWWWWWWWLWWWWWWWWWWWWWWWWWWWW 
WWWWWWWWWWWWW WWW WWW WWW АТАА 
Т Т А WWW 
АА К ДАДА, 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW 
WWWWWWWWWWWWWWWWWWWWWWWWWW АТАА 
WWWWWWWWWWWWWWWWWWWWW WWW WWW WWW WWW 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWW WWW WWW WA ры 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWlW 
ШИ 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWW WWW 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW 
WWWWWWWWWWWWWWWWWWWWW WWW WWW WWW WWW 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW WW 
WWWWWWWWWWWWWWWWWW WWW WWW WWW WWW WWW 
WWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWWW 
WWWWWWWWWWWWWWWWWWWWW WWW WWWWWWWWWWWWWW 
WWWWWWWWWWWWWWWWWWWWPHEW ! 
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The semicolon concatenates string data by displaying items right next to each 
other, with no spaces in between. Numeric data is also displayed in a continuous 
line format, with no spaces in between contiguous values. 

To illustrate this, change the string variable to a single-digit numeric variable. 
The program will look like this: 


2200 C=5 

2210 FOR Ісі TO 800 
2220 PRINT C; 

2230 NEXT I 

2240 PRINT "PHEW!" 
2250 END 


The number 5 is displayed as follows: 


>RUN 
5555555555555555555555555555555555555555 
5555555555555555555555555552555595955555595 
5555555555555555595555525555525555559595355555 
9555555959555555555595595555555555=95559595 
555555555555555555555555555555555555%556 
558555555555555525555555555555555555555555 
558555555555555555959553559555559559555595555555 
55555555555552555555555592223535959595955595555555 
5555555555555555599559525555555555555555955 
55555535555555555555555555555555555555555 
55555555558555555555555555555%56556555555 
355555555555555555555959555555555555555555 
5955555555555555555559555555555555555555 
55555555555955%55555555555555555555955555 
558555855525555555525555555555555535555555 
555555055559558555555555555555555555555555 
5555555555555555555555555555555555555565 
5555555555555555555555555555555555555555 
5555555555555555555555555555555555555555 
555553555555555555555525555555555555559555 
PHEW! 
> 


Now change C to minus 1: 


2200 C=-1 

2210 FOR I-1 TO 800 
2220 PRINT С; 

2230 NEXT I 

2240 PRINT "PHEW!" 


2250 END 

>RUN 
-1—1-1-1-1-1-1-1-1-1-1—-1-1-1-1-1-1-1-1-1 
e1e1-1-1-1-1-1-1-1-1-1—-1—1—-1-1-1-1-1-1-4 
$1-1—-1-1—-1-1-1-1-1—-1-1-1-1-1-1-1-1-1-1-1 
—-1-1—-1-1-1-1-1-1-1-1-1-1-1—1-1-1-1-1-1-4 
*1-1—1—-1-1—-1—1-1-1-1—1—-1-1-1-1-1-1-1-1-—41 
-141951-1-1-1-1-1—1-1-1-1-1-1-1-1-1-1-1-1 
-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1 
-1-1-1-1-1-1-1-1-1-1-1-1-1—-1-1-1-1-1-1-1 
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--і|--1--1--1--.-2--1--1--1--1--1--1-!1--1--1--1--!1--1--7-- 


-і--1.-1.-1.-1--1--1--1--1--1--1--1--1.-71--1--1--1--1-- 


-1.-.1--1--1--1--1--і--1--1--1--1--1--1--і1--1--1--1--1--” 


-»1--1--1--1--1--1--1--1--!--1--і1--1--1--1--1--1..1--1.- 


к. р jud jab көзе duh лға ка тарал та тара қараға ға ғара ға 


- 1 -»1.--1--1-»1--1-»1-»,1--1--1--1--1--1--1--1--1--1.-.1.- 


кә һа 


—1—1-—1—1-—1—1—1—1-—1—1-—1—1—1—1.—1.—1— 


кек. ра Ба jd duh eh Pub jd jd jad jud jad род jud jh m ара ғал jub ju ға раға [л je а Pe je }=^ (А 
ға ға deb ра jet БА jud jad deb je je р je jb ра рд ра ғаға dA ғара ғара [м5 duh de jad р ра а А 
de Б dh һа jab ра jad je duh (ju ju а jh р ра ра Һа ра duh de ра dub рь du ju (eh de рь з de dee га 
de dm н ра jad ju eh jad Б je jah jud а ра þad je jh ыл de je маралға А а а а на eb а а ра 
We eh н geh на duh eA (eA de eb eh рл рна ра pmd je рь кекете qeh je je карата deb je pad dA P P 
каға на de Һа duh duh deb jud рь geb һал ра de e^ ju ju duh ju dem je duh de de de (je deb je ра ра а ра 
на р jad de ға duh ра je je duh pud duh Buh je eA ju deb uA de^ de кара Pe pud jud ра Ба БА а а jm БА 
de МА e ра pd duh а ра ғара ра duh je je jb jh je je je jeh je je de jnd А ра deb je je jua Ph jet 
на de Б duh Ба ju ju je jud ра jen jod Beh fad jad jub jmb ғара ға pud ju к. uA je л je Pub jb а de PA 
кь de deb ра je ра ра jh pud ju а je jh Pub de һа je ра һа ра ғара je je а а je Geb je ња н Ба 
ке к. Б jod jud jd ub Ба uA (jh ра {мд fuh ju je һа jah ра jh ға dj je je зара jud ра а Beh ра Pe | 


нь ма нь н нь һа je je jm һа jm (eA ju jua dm je dA de je ва deb te de je dee jh Pe jh ju карама 
к. ка jd jd а je jh pA jad jd jud ра je һе ра рә jh Ье eh de je jh Deb (je deb ра Pe ға а [je je PA 
к. ph ка ju ва þad jad ма ғара һа һа ка Qe e ғ ра р je du de (Qu ғо ja Pe eA (je ре ға fm f ға 
de ка Б БА de ғара ғал jum jud jad рә de ju jm ja ра А |5 а ғара PA ҺА i jd ра ра ра ра de feb | 
ра Ба det de Ба ғара (deb jud jad jd jud jh geb jeR рд фара ка ғара jd jud jed фа кесте га | je Pe 
как. jt ка Ба ра jud А ра ра ра ра jah pA фара je БА Ба je шь ра Qe eA qe ра Ба ра duh ғара de^ 

1 

ка 


[ 
ка 
[ 
E ag eM ра на ра ға 


What has happened here? When C is —1, the program prints twice as many 
lines as when C is 5. It takes an extra position on the screen to display the minus 
sign. 

Multiple-digit numbers (including negatives) will scroll the display off the 
screen unless the FOR-NEXT index is adjusted. If C is changed to 2001, a four- 
digit display field is needed, so adjust the index from 800 to 800/4-200: 


2200 C-2001 

2210 FOR I-1 TO 200 

2220 PRINT C; 

2230 NEXT I 

2240 PRINT "PHEW!" 

2250 END 

2RUN 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
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2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
2001200120012001200120012001200120012001 
PHEW! 


Numbers are broken across the end of lines if necessary. This is because the 
semicolon (;) generates a continuous display, and nothing but an end of line can 
cause a return. Try the example above with C equal to 201 to see this. 


Using Commas 


ommas арреаҒпа after a variable or at the end of a PRINT statement treat the 
display as though it were tabbed at specific intervals. The rules for tabbing are 
different in Integer BASIC and Applesoft. 

Integer BASIC establishes five tab stops on the display screen. They are at col- 
umns 1, 9, 17, 25, and 33; they are eight spaces apart. Here is an Integer BASIC 
example: 
>NEW 
> 200 C=123 
> 210 FOR I-1 TO 100 
> 220 PRINT С. 
> 230 NEXT I 


> 240 PRINT "РНЕМ!" 

2 250 END 

>RLIN 

123 123 123 123 123 
123 123 123 123 123 
123 123 123 123 123 
123 123 123 123 123 
123 123 123 123 123 
123 123 123 123 123 
123 123 123 123 123 
123 123 123 123 123 
123 123 123 123 123 
123 123 123 123 123 
123 123 123 123 123 
123 123 123 123 123 
123 123 123 123 123 
123 123 123 123 123 
123 123 123 123 123 
123 123 123 123 123 


123 123 123 123 123 


114 APPLE ЇЇ USER'S GUIDE 
123 123 123 123 123 
122 123 123 123 123 
123 123 123 123 123 
PHEW! 


There must be at least one blank space ahead of a tab stop (except the first tab 
stop) or that tab stop will be inactivated. Thus, there must not be anything printed 
in column 8 for the second tab stop to be active, and so on. The following exam- 
ple program illustrates this with strings. 


>10 REM MUST DIMENSION STRING VARIABLES 

>20 DIM С%(9) 

2200 СФ=" 12245678" 

>210 FOR Ізі ТО 20 

2220 PRINT C$, 

>230 NEXT I 

2240 PRINT 

2250 END 

RUN 

12345678 
12345678 

12345678 
12345678 

12345676 


"PHEW!" 


12345678 12345678 
1234567353 
12345676 12345678 

12345673 
12245678 12 
12345678 12345473 
1234547% 12345678 12345678 
12345473 12345473 


345678 


PHEW! 


If you change C$ to “1234567,” all five tab stops will be used. 

There are some special conditions which govern tabbing with commas in 
Applesoft, as shown in Figure 4-1. 

To see how commas work in Applesoft using our example program, change 
the semicolon in the PRINT statement to a comma. This causes numbers to be 
displayed in three columns. At three numbers per line, the FOR-NEXT index will be 
3 * 20260. The complete program is shown at the top of the next page. 


First Tab Stop 
* Starts in column 1 


Second Tab Stop 

* Exists only if nothing 
printed in column 16 

* Starts in column 17 


Third Tab Stop 

* Exists only if nothing printed 
in cotumns 24-32 

* Starts in column 33 


16 spaces Кеткен E 6 spaces dics spaces wid 


FIGURE 4-1. Applesoft Tab Stops From PRINT With Commas 
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1200 C - 2001 

1210 РОК І = 1 TO 60 
1220 PRINT cC, 

1230 NEXT I 

1240 PRINT "PHEW!" 


1250 END 
RUN 
2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
. 2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
2001 2001 2001 
PHEW! 


Commas also work with strings. As an example, enter the following immediate 
mode program to display twenty lines of tabbed character data: 


JNEW 

1100 A$-"THREE" 
1110 BS="BLIND" 
1120 C$-"MICE" 

1210 FOR I-1 TO 20 
1220 PRINT A$;B$.C$ 
1230 NEXT I 

1240 PRINT "PHEW!" 


1250 END 


JRUN 
THREE BL IND MICE 


THREE BL IND MICE 
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THREE BLIND MICE 
THREE BL IND MICE 
THREE BL IND MICE 
THREE BL IND MICE 
THREE BL IND MICE 
THREE BL IND MICE 
THREE BL IND MICE 
THREE BL IND MICE 
THREE BL IND MICE 
THREE BL IND MICE 
THREE BLIND MICE 
THREE BLIND MICE 
THREE BLIND MICE 
THREE BLIND MICE 
THREE BLIND MICE 
THREE BLING MICE 
THREE BLIND MICE 
THREE BLIND MICE 
PHEW! 


As a further exercise, try letting B$ be VISIONARY instead of BLIND. If you 
studied Figure 4-1, it will come as no surprise to you that the third tab stop is not 
used. The word VISIONARY, starting in the second tab stop at column 17, prints 
into columns 24 through 32. Printing anything in columns 24 through 32 deacti- 
vates the third tab stop. 


PRINT FORMATTING FUNCTIONS 


We use the word formatting to describe the process of arranging information on a 
display screen so that the information is easier to understand or more pleasing to 
the eye. As we have seen, commas and semicolons help. Still, formatting could 
become a complex chore. For example, suppose you want to display a heading in 
the middle of the line at the top of the display screen. 

Here is an Integer BASIC program which uses commas to tab to the center of 
the display screen and print a heading. It also uses the CALL statement, which we 
recently discovered, to position the cursor at the upper lefthand corner of the dis- 
play screen (see Appendix D). 


2NEW 


25 REM MUST DIMENSION STRING VARIABLES 
>10 DIM HD$(30) 
2500 REM CLEAR THE SCREEN AND 
2510 REM MOVE THE CURSOR To THE 
29520 REM UPPER LEFT CORNER 
29330 CALL -936 
2540 HDS="TOP SECRET" 
2550 REM TAB TO CENTER ОҒ SCREEN 
29555 КЕМ REM THEN PRINT HEADING 
2960 PRINT "","",HD$ 
29570 END 
2RUN 

ТОР SECRET 
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The heading is approximately centered on the display screen. Were the heading 
longer, say REPORT ON HEAVY HYDROGEN, it would not be centered on the dis- 
play screen. (Try it) This new heading will be approximately centered if you 
remove one of the commas and its adjoining null string, so that the heading is dis- 
played starting at the second tab stop rather than the third. 

We could use the same technique for displaying headings in Applesoft. But 
Applesoft has PRINT statement formatting aids that are much easier to use: the 
SPC, TAB, and POS functions. 


SPC Function 


SPC is a space-over function. You include SPC as one of the terms in a PRINT 
statement; after the letters SPC you must enclose (in parentheses) the number of 
character positions that you wish to space over. For example, we could center the 
heading TOP SECRET with the following: 


1100 REM CLEAR SCREEN 

1110 HOME 

1120 REM SPACE OVER AND DISPLAY 
1130 PRINT SPC(15):"TOP SECRET" 
1140 END 


JRUN 
TOP SECRET 


Notice the semicolon after SPC. A comma after SPC will start displaying text at 
the next tab stop following the number of spaces specified by SPC. 

Any time you include the SPC function in a PRINT statement you simply cause 
the next printed or displayed character to be moved over by the number of posi- 
tions specified after SPC; nothing else is changed. 


TAB Function 


TAB works much the same as typewriter tabbing. 

Suppose you want to print or display information in columns. You must first 
calculate the character position where each column is to begin. А form like the 
one in Appendix L is handy for this. In Figure 4-2, columns begin at character 
positions 1, 15, and 31. Now instead of using blank spaces as you go from col- 
umn to column, you simply insert a TAB function after each entry in the PRINT 
statement. 

Consider one line of the display illustrated in Figure 4-2. Counting character 
positions, we could display the line without tab stops, as follows: 


110 ?" JONES, P.. 431-295-6277 1420.00" 
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- "Column: Number 


BEDEHUBEDH 
PERCE eer BRE 
ҮП ЕНЕСІН 


FIGURE 4-2. Determining Screen Character Positions 


Instead of inserting blank spaces, we could use the SPC function and shorten the 
statement as follows: 

110 ?"JONES;F.J": SPCC72s3"431-259-6277"3 SP 

с(5) : "1420.00" 
But tabbing is easier because you tab to a known column number instead of 
counting spaces: 


110 ?"ЈОМЕЅ,Р. 2": TABC16)3 "431-25-6277"5 T 
АВ (32) 5 "1420.00" 


Determining the Cursor Position 
(Horizontal) 


POS is the last of the Applesoft formatting functions. POS tells you which column 
the cursor is in. The position is expressed as a number, equal to the column num- 
ber where the cursor is blinking. You always include a dummy argument of O after 
POS, as follows: РО5(0). 

The following statement demonstrates the capability of POS: 


J?"CURSOR POSITION IS"sPFüOZ(O) 
Execute this statement in immediate mode. The display will appear as follows: 


l?"CURSOR POSITION IS "sPCOS(CO) 
CURSOR POSITION IS 19 
The cursor was at character position 19 after displaying CURSOR POSITION IS. If 
you add some spaces after IS, and before the closing quotes, you will change the 
number 19 to some larger number. 
In Integer BASIC you can simulate the POS(O) function with PEEK(36) to deter- 
mine which column the cursor is currently in. Here is the previous example re- 


stated: , 
SPRINT "CURSOR POSITION IS "3PEEK (24) 


CURSOR POSITION IS 19 
Note that display screen columns are numbered O through 39 for POS, 
PEEK(36), and PRINT SPC. Columns are numbered from 1 to 40 for PRINT TAB, 
and for two instructions we will cover soon, HTAB and TAB (Integer BASIC). 
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Determining Cursor Position 
(Vertical) 


PEEK (37) will give you the row which the cursor is currently on. 
Rows are numbered O through 23 for PEEK(37), but 1 through 24 for VTAB 
(covered in the next section). 


CURSOR CONTROL AND 
SPECIAL VIDEO EFFECTS 


There are a number of BASIC statements which increase the versatility of the 
Apple Il display screen. These include the FLASH, INVERSE, SPEED, NORMAL, 
HOME, VTAB, and HTAB/TAB statements. Most of these are available only with 
Applesoft. There are a number of graphics statements as well; these are covered 
in Chapter 6. 


Positioning the Cursor 


We have already covered several ways of controlling the cursor position by using 
commas and semicolons with the PRINT statement. The Applesoft formatting 
functions SPC, TAB, and POS are also useful in positioning the cursor. 


Clearing the Display Screen 


You can clear the display screen and position the cursor to the home position 
(upper left corner) with the statement CALL —936, or in Applesoft with the HOME 
statement. Try typing these (one in Integer BASIC, the other in Applesoft): 


2CALL -936 


JHOME 


Horizontal and Vertical 
Positioning 


There are two statements which together allow you to move the cursor to any 
position on the screen. VTAB moves the cursor vertically and HTAB (TAB in 
Integer BASIC) moves the cursor horizontally. You must specify the line number 
for VTAB and the column number for HTAB. The top line of the screen is 1 and 
the bottom line is 24. The leftmost column of the screen is 1 and the rightmost 
column is 40. 

The following program uses these two statements (in Applesoft) to position 
the cursor and display an asterisk at that position. If you are using Integer BASIC 
use TAB instead of HTAB on lines 90 and 120. 


120 APPLE Il USER'S GUIDE 


90 НТАВ 1: УТАВ (1) 
100 INPUT "ROW?"SR 
110 МРОТ "COLUMN^" $C 
120 УТАВ R: НТАВ C 
130 PRINT "s"; 

140 GOTO 90 


Тһе INVERSE and NORMAL Statements 


You can reverse the black and white parts of characters on the display screen; the 
INVERSE statement does this. Once the INVERSE statement is executed, every- 
thing displayed by PRINT statements appears in reverse video mode. The charac- 
ters you type on the keyboard will still echo in normal video mode, however. 

The Apple Il returns to normal video mode when it executes a NORMAL com- 
mand. 

To see how these two commands work, try this (the shaded characters will be 
in reverse video): 

JINVERSE 


J?"BLACK ON WHITE" 
BLACK ON WHITE 


JNORMAL 


12"ЫНІТЕ ON BLACK" 
WHITE ОМ BLACK 


INVERSE and NORMAL are not available in Integer BASIC. 


The FLASH Statement 


Not only can you reverse the black and white parts of characters, you can make 
characters flash back and forth between normal and reverse video. Use the 
FLASH statement to do this. Here again, NORMAL causes the Apple Il to revert to 
normal video. 
Here is an example (the shaded areas will be flashing): 
IFLASH. 


J?"FLASH IN THE FAN" 
FLASH IN THE PAN 


JNORMAL 


J?"STEADY AS RAIN" 
STEADY А5 RAIN 


FLASH is not available in Integer BASIC. 


The SPEED Statement 


The rate at which characters display on the screen is variable. You can slow it 
down from its normal rate with the SPEED statement. 
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The following program illustrates how SPEED works. 
J100 INPUT "SPEED = ":SP 


1110 SPEED = SP 

1120 FOR СТ = 1 TO 3 
Ji30 PRINT "HIC" 
1140 NEXT 

1150 PRINT "HICCUP" 
1160 SPEED = 255 
1170 ЕМП 


The value of the expression (e.g., the value of SP on line 110) adjusts the dis- 
play speed; O is slowest and 255 is fastest. SPEED also affects the rate at which 
characters are sent to other devices, not just the display screen. 

SPEED is not available in Integer BASIC. 


TEXT WINDOWS 


Normally, the Apple Il actively uses all 24 lines and 40 columns of its display 
screen in text mode. Using POKE statements, you can alter the size and position 
of this text window. Four memory locations control the size, shape, and position 
of the text window, as shown in Table 4-1. 

You must be careful to observe the common-sense range limits shown in Table 
4-1 when you set a text window. Trying to set windows outside these bounds will 
have unpredictable results. 

The sample program below sets a two-line text window in the middle of the 
display screen for inputting a numeric value. To appreciate the full utility of this 
technique, try entering some non-numeric values and observe what happens with 
the error messages. Notice also that setting the text window does not clear the 
remainder of the screen, nor does it move the cursor into the text window. You 
must provide separate BASIC statements to do this. 


TABLE 4-1. Text Window Memory Locations 


Left Margin O to 39 
Width 1 to 40 minus Left Margin 
Top Line O to Bottom Line 


Bottom Line Top Line minus 24 


122 APPLE il USER'S GUIDE 


1000 REM SET WINDOW TOP LINE. WIDTH, LEFT MARG.: & BOTTOM 
LINE 

1010 T = 10:0 = 20:1М = 11:B = 13 

1020 REM CLEAR SCREEN 

1030 CALL - 936 

1040 REM SET TEXT WINDOW FOR INPUT 

1050 GOSUB 3200 

1060 REM SURROUND INPUT WINDOW WITH ASTERISKS 
1070  GOSUB 3000 

1080 КЕМ MOVE CURSOR INSIDE WINDOW; INFUT 
1090 УТАВ T + 2 

1100  INPUT M1 

1110 REM RESET WINDOW ТО FULL SCREEN 
1120 GOSUB 3300 

1130 REM MOVE CURSOR Та BOTTOM LINE 
1140 VTAB 23 

1150 END 

2990 REM SURROUND WINDOW WITH ASTERISKS 
3000 VTAB T + 1 

3010 GOSUB 3100 

3070 VTAB B + 1 

3030 GOSLIR 3100 

3040 RETURN 

3090 REM PRINT ASTERISKS 

3100 FOR I= 1 ТП W 

S110 PRINT "+"; 

3120 NEXT I 

31320 RETURN 

3190 КЕМ SET INPUT TEXT WINDOW 

3200 PIKE 32,T 

3210 POKE 33,W 

3220 РПКЕ 34,1.М 

3230 POKE 35, В 

3240 RETURN 

3290 REM СЕТ FLULI.-SCREEN WINDOW 

3300 POKE 32,0 

3310 POKE 23.40 

3320 POKE 34,0 

2330 POKE 35.24 

3340 RETURN 


THE CHR$ FUNCTION: PROGRAMMING 
CHARACTERS IN ASCII 


In the last chapter we discussed how you can generate invisible characters like 
CrRL-G, which makes the Apple Il beep. But there are some characters (both visi- 
ble and invisible) which you cannot type directly on the keyboard. These include 
“Г” and “А”. You can generate these characters in Applesoft with the CHR$ func- 
tion. 

In order to understand the CHR$ function, you must understand how charac- 
ters are stored in the Apple Il memory. It's really very simple. Computer memory 
can store numbers, but not characters. So characters are converted to numeric 
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codes. The Apple Il uses the same code as all other microcomputers, the ASCII 
code (American Standard Code for Information Interchange). For example, the 
ASCII code for the letter А is 65, for B itis 66, С is 67, and so on. You will find a 
complete table of ASCII codes in Appendix |. Whenever the Apple Il is dealing with 
strings, it interprets numeric values as ASCII codes for characters. 

In Applesoft, if you cannot press a key to include a character within a text 
string, you can still select the character by using its ASCII code. 

The CHR$ function translates an ASCII code number into its character equiva- 
lent. For example, to create the symbol “%”, first find its ASCII code in Appendix І. 
Then use the code with CHR$ as follows: 

JPRINT CHR$(36) 
$ 

Experiment in immediate mode using any ASCII code from O to 255. | 

You can use the CHR$ function in conjunction with regular strings in a PRINT 
statement as follows: 

J?CHR$(34)3s "ZOLINIIS ! "3 CHR$ C34) 
"ZOLNDS ! " 

The CHR$ function lets you include otherwise unavailable characters such as 

carriage return and quotation marks as part of a string. 


PROGRAMMING DATA ENTRY 


The goal of any program should be to minimize data entry errors and make it easy 
for an operator to spot and correct errors that do occur. There are ways to orga- 
nize data entry which tend to minimize errors. 

First, enter a whole functional block of data and then process it. It is poor pro- 
gramming practice to process each piece of data as it comes in from the 
keyboard. 

A mailing list program, for example, requires names and addresses to be 
entered as data. You should treat each name-and-address as a single functional 
unit. In other words, your program should ask for the name and address, allowing 
the operator to enter all of this information, and then change any part of it. When 
the operator is satisfied that the name and address is correct, the program can go 
ahead and process it. Then the program should ask for the next name and 
address. 

In the case of a mailing list program it would be poor programmng practice to 
ask for the name, process it immediately, then ask for each line of the address, 
treating each piece of the name and address as a separate and distinct functional 
unit. 

It is a good idea to organize data entries so that data items remain on the dis- 
play screen for a while after they have been entered. That gives the operator more 
opportunity to notice an error and correct it. If entries disappear as soon as they 
are entered, there is no chance for an operator to casually notice an error. Of 
course, the operator must have some way of correcting previous entries. 
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Under some circumstances entering data in functional blocks with ample 
opportunity for review and correction is not the best way to go. This set of cir- 
cumstances is a surprising one. It occurs when a very large amount of data must 
be entered by keyboard operators. For example, suppose a keyboard operator 
must enter hundreds of names and addresses a day. Experience has shown that 
the highest volume of accurate data entry can be achieved by having the 
keyboard operator ignore all errors on first entry. The data entry program does not 
allow for the correction of any errors, even if the operator notices them right 
away. Operators must ignore errors and carry on entering data as fast as possible. 
Under this scheme, data is entered twice, preferably by different operators. A 
separate program compares the two sets of entries. The chances of both opera- 
tors making the same error are so small that you can count on all errors being 
caught as differences between the two sets of data entry. A subsequent program 
allows reentry of incorrect data. 


Interactive Data Entry 


A program with interactive data entry guides users with displayed instructions 
and prompt messages. To demonstrate interactive data input we will begin with a 
very simple example. We will make changes to a program you will remember from 
earlier in the chapter so that it uses interactive data entry procedures, thereby 
making the program easier to use. 
Here is the program: 
200 C$ = "W" 
210 FOR I = 1 TO 800 
220 PRINT C$: 
230 NEXT I 
240 PRINT "PHEW!" 
250 END 
As illustrated, this program will display 800 W characters followed by the 
word PHEWI. It works the same in Integer BASIC or Applesoft. 
Suppose we want to display any character, instead of just W. 
First eliminate the assignment statement in the program. Remember that to 
delete a program statement, you type the line number followed immediately by a 
RETURN. 


210 FOR I = 1 TO 800 
220 PRINT C$; 

230 NEXT I 

240 PRINT "PHEW!" 
250 END 


Line 200 is no longer in the program. 
Type in the statement C$z''X'" in immediate mode, then run the program. 


3 СФ- " X " 


JRUN 
PHEW! 
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The word PHEW! is printed, but the X's are not. Obviously the value of C$ is 
not being transmitted to the program. 

RUN clears all numeric variables to O and all strings to null before beginning 
execution of a program. So C$ was set to null, and a null character was printed in 
the program loop (a null is “nothing”: it does not print nor does it move the cur- 
sor). 

Is there a way to transmit a different value of C$ each time you run the pro- 
gram? Instead of using RUN, which initializes variables, use GOTO 210 (210 
being the line number of the first line of the program). This does not change any 
variable values. 


IC$="X" 


150Т0 210 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
PHEW' 


There are only two steps in running the program, but the procedure is awk- 
ward. You must type in a line (the assignment statement), and if you enter RUN 
instead of GOTO, you must start all over. But the program could fetch the display 
character while it is running, using the INPUT statement. 

Type in the following line: 


1200 INPUT C$ 
Now list the program and make sure you entered the line correctly. 
JLIST 


200 INPUT C$ 

210 FOR I = 1 TO 300 
220 PRINT C$; 

230 NEXT I 

240 PRINT "PHEW!" 
250 END 
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Run the program. The cursor drops down one line. (In Applesoft a question 
mark appears next to the cursor, too.) Enter any single character (and press 
Return). The character you enter is displayed 800 times. Run the program again. 
Enter a different character. The display appears with the new character. Note that 
if you try to enter more than one character at a time in Integer BASIC, the program 
halts with a +++ STR OVFL ERR. This is because C$ has not been dimensioned. 

This is a real improvement over the original program. However, it is a little 
mystifying to have the cursor just blinking away on the screen while it waits for 
you to press a key. Add a prompt line to the beginning of the program, asking for a 
key to be pressed. Type in the line: 


1190 PRINT "ENTER ONE CHARACTER" 


List the program and check the new line for any errors. 

Now the program gives operating instructions. Run the program several times 
to display different characters and note how much easier the program is to use. 

There is one important modification left to make. If you want the program to 
repeat automatically, use a GOTO statement to go back to the beginning of the 
program instead of ending it. Then you won't have to type in RUN to reexecute 
the program. Add the following line: 


1250 GOTO 190 


Now it is even easier to use the program. Enter RUN and follow directions. 

Of course, you have to use CrRL-C to end the program. This can be eliminated 
by programming one particular key to terminate program execution. For example, 
the Return key could be programmed to terminate execution. Неге is how: 


190 PRINT "ENTER ONE CHARACTER" 
200 INPUT C$ 

205 IF C$ = "" THEN END 

210 FOR I = 1 TO Зоо 

220 PRINT C$; 

230 NEXT I 

240 PRINT "PHEW!" 

250 GOTO 190 


Line 205 checks to see if C$ has a null value. This will happen if you do not 
enter a character in response to the INPUT statement on line 200, but only press 
the RETURN key. 

As a final task, you might read over the program and add remarks. Include a 
comment on how the FOR-NEXT index 800 was devised; you can optionally put 
the remark on the same line, using a colon to separate statements: 


210 FOR Ісі TO 800:REM 800/40=20 LINES 
Add a reminder that a null entry ends the program: 
203 REM END PROGRAM ON NULL ENTRY 


Finally, add a few lines at the beginning of the program to describe it, and give it a 
title. The final program is shown in Figure 4-3. 


Chapter 4: ADVANCED BASIC PROGRAMMING 127 


10 REM #422048 BLANKET ITIITII 
20 REM CONTINUOUS-LINE DISPLAY OF ONE 
30 REM CHARACTER ENTERED FROM 
40 REM THE KEYBOARD 
БО REM ** 449545442 43422227EP(U(P 
190 PRINT “ENTER ONE CHARACTER” 
200 INPUT C$ 


203 REM END PROGRAM ON NULL ENTRY 

205 IF C$ -““ THEN END 

210 FOR I = 1 TO 800: REM 800/40 = 20 LINES 
220 PRINT C$; 

230 NEXT I 

240 PRINT “PHEW!” 

250 GOTO 190 


FIGURE 4-3. Program BLANKET 


Prompting Messages 


Any program that requires data entry should prompt the operator by asking ques- 
tions. Questions are usually displayed on a single line and demand a simple 
response such as “yes” or “по.” For example, the following message might be 
displayed: 


DO YOU WANT TO MAKE ANY CHANGES? 


An operator must respond to this message by entering the word YES or the 
word NO. Frequently just the letter Y or N suffices. Another common example 
may give the operator a number of options. The message: 


WHICH ENTRY DO YOU WISH TO CHANGE? 


may allow the operator to enter a code which identifies an allowed entry. 

Programs that control this type of dialogue should be written as independent 
subroutines which do not make any assumptions nor depend on knowledge of 
programs which call them. This has three implications: 


1. You cannot assume that the space where the prompt message will be 
displayed is blank. If it is not blank, then the message will overwrite 
whatever was previously there. But existing characters not 
overwritten by the prompt message will still be there. This could be 
unsightly from the operator's viewpoint. It can be confusing and lead 
to entry errors. The following subroutine will erase the number of 
spaces determined by the value of variable ER: 


3000 КЕМ ERASE SFACES 
5010 FOR I = 1 TO ER: PRINT ""5: NEXT I: RETURN 
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2. А subroutine must receive information from the calling program. For 
example, if a subroutine asks the operator to enter a number, then any 
program that uses it must specify the minimum and maximum 
acceptable entry value. 


3. The subroutine must return the operator's response to the calling 
program. This may be a character (e.g., Y or М), a word (e.g., YES or 
МО) or a number. 


Subroutine logic cannot deduce where on the screen it should display the 
prompt message, however. It is therefore fair to demand that the calling program 
position the cursor correctly before it calls the subroutine. 

Now look at the subroutine needed to ask a question that requires a reply of Y 
for yes, or N for no. We will use a PRINT statement to ask the question, followed 
by an INPUT statement to receive a one-character response. We will clear parts of 
the display screen with the subroutine above. Here is a program with the 
subroutines: 


100 REM MOVE CLIRSOR 

140 УТАВ 1 

150 REM CALL SUBROLITINE TO GET RESPONSE 
140 GOSUB 3020 


170 END 
3000 REM ++ GET Y/N RESPONSE ++ 
3010 REM 


3020 С = POS (0): REM REMEMBER CURSOR COLUMN 
3030 R = PEEK (37): REM REMEMBER CURSOR ROW 
3040 REM CLEAR SPACE FOR QUERY 

3050 ER = 35: REM CLEAR 35 SPACES 

3060 GOSUE 5010 

3070 НТАВ C + 1: REM REPOSITION CURSOR 

3080 PRINT "nO YOU WANT TO MAKE ANY CHANGES"; 
3090 INPUT R$ 

3100 IF R$ = "Y" OR R$ = "N" THEN RETURN 

3110 REM IMPROPER RESPONSE 

3120 VTAB R + 1: REM REPOSITION CURSOR (VERT) 
3130 GOTO 3050: REM TRY AGAIN 

S000 REM ++ ERASE SPACES ++ 

3010 FOR I = 1 TO ER: PRINT “ "s: NEXT I: RETURN 


Next consider dialogue which allows an operator to enter a number. We will 
design a subroutine to accept a response no smaller than the value of variable LO 
and no larger than the value of variable HI. The subroutine will return the entered 
number in variable NM. Here is the necessary program: 


100 REM SET RANGE AND POSITION CURSOR 
140 LO = LEHI = 10 

150 УТАВ 1 

140 КЕМ CALL SUBROUTINE TO GET RESPONSE 
170 БОЗОВ 3500 

180 END 

S900 REM ++ GET NUMERIC RESPONSE ++ 
3510 REM ++ LOSZZRESPFONSECZHI-t 
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3920 REM ++ NM IS RESPONSE ++ 

3930 GOSUB 5110: REM WHERE IS CURSOR NOW? 

2540 REM CLEAR SPACE FOR QUERY 

3550 ER - 35: REM CLEAR 35 SPACES 

2560 GOSUB 5010 

3570 HTAB C + 1: REM REPOSITION CLIRSOR 

3980 PRINT "WHICH FIELD DO YOU WANT TO CHANGE (1-10)"; 
S590 INPUT NM 

3400 IF NM > = LĒ AND NM < = HI THEN RETURN 
3610 REM IMPROPER RESPONSE 

3620 VTAB R + 1: REM REPOSITION CURSOR (VERT) 
3630 GOTO 3550: REM TRY AGAIN 

S000 КЕМ ++ ERASE SPACES ++ 

5010 FOR І = 1 TO ER: PRINT ""5: NEXT I: RETURN 
5100 REM ++ REMEMBER CURRENT CURSOR POSITION ++ 
5110 С = PEEK (36): REM . COLUMN 

9120 R = PEEK (37): REM ROW 

5130 RETURN 


Can you change the subroutine so that it accepts two-digit inputs? Try to write 
this modified program for yourself. If you cannot do it, then wait until later in the 
chapter where you will find the necessary subroutine in the program which con- 
trols the input of a date. 

There is another simple modification you can make to both of the dialogues we 
have described. The prompt message printed in both programs could be supplied 
by the calling program via a string variable. This would make the subroutines more 
general purpose. Can you rewrite the programs to accept a message provided by 
the calling program? 


Error Detection and Control 


If you want to write a really thorough program you will make every effort to antici- 
pate errors that a user of your program might make. Your program will catch entry 
errors and force the user to reenter values that would cause the program to halt 
abnormally (termed bombing, bombing out, or blowing up in computer jargon). 

It is true that the Apple Il will catch some kinds of data entry errors for you. It 
will not accept alphabetic entry when inputting a numeric value with a statement 
like INPUT A. If you try to enter letters in response to such a statement, the Apple 
ll issues an error message and asks you to reenter the value. 

Built-in error checking capabilities are limited, though. It is very possible to 
enter the right kind of value (e.g., numeric or string) which has an unacceptable 
value. That is, the value may cause a program error further down the line. Here is a 
short program that illustrates the problem: 


100 INPUT X 
200 PRINT 100 / X 
300 END 
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If you enter O in response to the INPUT statement, the program will fail when it 
tries to divide by O in the PRINT statement. It'S easy enough to avoid this. The 
following lines will check the input to make sure it is not O, and will request reentry 
if it is. 

110 IF X< > О THEN 200 


120 PRINT "МОТ ALLOWED...RE-ENTER" 
130 GOTO 100 


By extending the principle illustrated in this example, you can see how easy it is 
to check an entered value for the correct range. Depending on the circumstances, 
it may make sense to do range checking with the Applesoft ON-GOTO or ON- 
GOSUB statements (computed GOTO or GOSUB in Integer BASIC), rather than a 
series of IF-THEN statements. There is an example of more extensive error check- 
ing in the next section. 


The ONERR GOTO 
and RESUME Statements 


Applesoft has a special statement that allows you to trap errors which it 
catches — before it displays an error message and halts program execution. Here 
is an example: 


SO ONERR GOTO 2000 


Once such a statement has been executed, Applesoft will branch to the 
specified line number if it detects an error. It will also place a numeric code 
describing the error in memory location 222, which you may inspect with the 
PEEK statement. Table C-1 in Appendix C lists error conditions detectable by 
ONERR GOTO. 

The usual procedure for handling errors with ONERR GOTO is to write an error 
handling routine which the ONERR GOTO branches to when an error occurs. At 
the end of this routine, the RESUME statement causes a branch back to the begin- 
ning of the statement where the error occurred. Alternately, a GOTO statement 
will transfer to any program line. Write the error handling routine so it takes 
different actions depending on the nature of the error and the current state of the 
program, which can usually be determined by inspecting the values of key varia- 
bles. 

To negate the ONERR GOTO and restore the Apple ll to its normal automatic 
error handling state, use the statement POKE 216,0. 

The following program demonstrates the use of ONERR GOTO. In this pro- 
gram, any errors that cannot occur as the result of keyboard entries are treated as 
fatal errors, with an appropriate advisory message. Entry errors are announced 
and reentry requested. 
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30 ОМЕКК GOTO &000 

200 PRINT "ENTER A STRING VALUE" 

210  INPUT X$ 

220 PRINT "ENTER А NUMERIC VALUE" 

230 INPUT X 

240 PRINT "ENTER AN INTEGER VALLE" 

250 INPUT ХХ 

260 GOTO 200 

$00 КЕМ END OF PROGRAM 

510 PRINT "LAST ENTRIES WERE ":Х%:4» "3X3" AND "5X7 
515 POKE 216,0: REM TURN OFF ON ERR 

520 END 

3000 КЕМ ++ ERROR HANDLING ROUTINE ++ 

8010 E = PEEK (222): REM GET ERROR NO. 

$020 IF E = 255 THEN GOTO 800: REM END PROGRAM ON CTRL-C 
3030 IF E = 53 OR E = 176 OR E = 254 THEN 8100 

8035 INVERSE 

3040 REM PROGRAMMING ERROR DETECTED 

8050 PRINT “ARRGH! ERROR NO. "SEs" FOUND." 

8055 PRINT “WRITE DOWN THIS NUMBER" 

3060 PRINT “AND A DESCRIPTION OF WHAT WAS GOING ON." 
8070 PRINT “CALL A PROGRAMMER FOR HELP." 

8080 PRINT "LEAVE THE COMPUTER ON!" 

3090 NORMAL : STOP 

8100 REM INPUT ERROR DETECTED 

8110 PRINT "“%: REM CTRL-G CHARACTERS IN QUOTES 
8130 PRINT "ERROR...TRY AGAIN" 

8140 RESUME 


Entering a Valid Date 


In this section we will develop a program that uses many of the techniques pre- 
sented so far in this chapter. This program uses some BASIC functions and state- 
ments available only in Applesoft. The program can be written in Integer BASIC; 
you may wish to make the conversion. 

Most programs at some point need relatively simple data input: more than a 
simple yes or no, but less than a full screen display. Consider a date. 

You must take more care with such simple data entry than might at first appear 
necessary. In all probability the date will be just one item in a data entry sequence. 
By carefully designing data entry for each small item, you can avoid having to 
restart or back up in a long data entry sequence whenever the operator messes up 
a single entry. 

We will assume that the date is to be entered as follows: 


MM — DD — YY 


| Do 


LL —— Separator 
Day of the month 
Separator 
Month 
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The month, day of the month, and year are each entered as a two-digit num- 
ber, without any terminating RETURN. 

The program supplies the dash that separates the entries. Depending on your 
personal preferences, it might be a slash or any other visually pleasing character. 
In many parts of the world the day of the month precedes the month. 

Program data entry so that it is pleasing to the operator's eye. The operator 
should be able to see immediately where data is to be entered, what type of data 
is required, and how far the data entry process has proceeded. A good way of 
showing where data is to be entered is to reverse the data entry field. For example, 
the program that asks for a date to be entered might create the following reverse 
field display: 


Cursor flashing at entry character 
position 


Data must be entered into these 
character positions 


You can create such a display with the following program: 


10 НОМЕ : VTAB 3: НТАВ 20: REM POSITION FOR INFUT 
20 IW = 2: GOSUB 1100: REM 2-CHAR INPUT FIELD 

30 PRINT "-'; 

40 GOSUR 1100: REM 2-CHAR INPUT FIELD 

50 PRINT "-"5 

40 GOSUB 1100: REM 2-CHAR INPUT FIELD 

70 УТАВ 3: HTAR 20: REM REPOSITION ТО START OF INPUT FIELD 
80 END 

1090 REM ++ DISPLAY "IW" REVERSE-BLANKS ++ 

1100  INVERSE 

1110 FOR I = 1 TO IW: PRINT " "5: NEXT I 

1120 NORMAL 

1130 RETURN 


The program above includes statements that position the date entry to begin at 
column 21 on row 3. It also clears the screen so that residual garbage on the 
screen does not surround the request for a date. After displaying the date entry 
field, the cursor moves back to the first character position of the first entry field, 
although this is not apparent because of the END statement. 

Try using an INPUT statement on line 80 to receive the first part of the date: 
the month. This could be done as follows: 

ЗО INPUT M$ 
90 END 

Enter statements on lines 80 and 90, as illustrated above, and execute them. 
As you see, the INPUT statement will not do. Apart from the fact that a question 
mark displaces the first reverse field character, pressing Return at the end of the 
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entry erases the rest of the display line. This is an occasion to use the GET state- 
ment. Add the following program lines: 


SO ППСИН 1200:MM$ = C$: REM GET 15Т MONTH DIGIT 

70  GÜUSUBR 1200:ММ% = ММФ + C$: REM БЕТ 2NU MONTH DIGIT 
1190 REM ++ ACCEFT CINE INFLT CHARACTER ++ 

1200 GET C$ 

1210 FRINT C$:: REM ECHO KEYSTROKE 

1220 RETURN 


These statements accept a two-digit input. The input is displayed in the first 
reverse field of the date. The two-digit input needs no Return or other terminating 
keystroke. The program automatically terminates the data entry after two charac- 
ters have been entered. 

Three two-digit entries are needed: for the month, the day, and the year. Rather 
than repeating satements on lines 80 through 90, we will put these statements 
into a subroutine and go to it three times, as follows: 


tO GOSUB 3300: MM$ = CC$: КЕМ GET MONTH 

70 PRINT "-";: REM SPACE OVER TO NEXT FIELD 
180 СПОШИЕ 1300:00% = CC$: КЕМ БЕТ DAY 

190 PRINT "-":: REM SPACE OVER TO NEXT FIELD 
x30 GOSUB 1300: YY$ = CC$: REM GET YEAR 

ЕЭО ENN 

1290 REM ++ GET A 2 
1300 GOSUB 1200:0707$ 
1320 RETURN 


“CHARACTER INPUT ++ 
= CC$ + C$: REM GET 2ND CHARACTER 


The variables MM$, DD$, and YY$ hold the month, day, and year entries, 
respectively. Each entry is held as a two-character string. 

There are two ways in which we can help the operator recover from errors 
while entering a date. 


1. The program can automatically test for valid month, day, and year 
entries. 


2. The operator can be given a means of restarting the data entry. 


The program can check that the month lies between 1 and 12. The program 
will not bother with leap years, but otherwise it will check for the maximum num- 
ber of days in the specified month. Any year from OO through 99 will be allowed. 
Any invalid entry will cause the entire date entry sequence to restart. 

If the operator presses the Return key, then the entire date entry sequence 
restarts. Our final date entry program now appears as follows: 


10 HOME = VTAR 2: НТАВ 20: REM POSITION FOR INPUT 


19 КСФ = CHRS (13): REM ASSIGN RESTART-ENTRY CHARACTER 
17 REM 

18 КЕМ MISPLAY THREE Z-CHAR. INPUT FIELDS 

19 REM 


20 IW = 2: GOSUR 1300 
30 PRINT “-"; 
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40 GOSUB 1100 

SO PRINT "-”; 

60 GOSUE 1100 

65 PRINT ""s: REM CTRL-G(BELL) 

67 REM 

68 REM GET THREE FIELD ENTRY 

49 REM 

70 VTAB 3: HTAR 20: REM REPOSITION ТП START ОҒ INPUT FIELD 
79 КЕМ 

80 REM GET MONTH 

81 REM 

90 GOSUB 1300: IF C$ = КСФ THEN GOTO 10: REM CHECK FOR 
ENTRY RESTART 

100 MM = VAL (00%): REM MONTH NUMBER 

110 IF MM c 1 OR MM > 12 THEN 10: REM CHECK FOR UNREAL. 
MONTH 

120 DT$ = CC$: PRINT "-":: REM ADVANCE TO NEXT FIELD 
125 КЕМ DETERMINE MAX. NG. OF DAYS THIS MONTH 

130 DM = 31: REM ASSUME 31 DAYS 

125 КЕМ UNLESS FEBRUARY 

140 IF MM = 2 THEN DM = 29 

150 КЕМ ОК AFR, JUNE, SEPT, NOV 

160 IF MM = 4 OR MM = 6 OR MM = 9 OR MM = 11 THEN DM = 30 
169 REM 

170 REM GET DAY 

171 REM | 
180 GOSUB 1300: IF C$ = КСФ THEN GOTO 10: REM CHECK FOR 
ENTRY RESTART 

190 DD = VAL (CC$): IF DD < 1 OR DD > DM THEN 10: REM 
RESTART IF ENTRY IS INVALID 

200 ПТФ = ПТФ + "-" + CC$: PRINT "-":: REM ADVANCE TO 
NEXT FIELD 

269 REM 

270 REM GET YEAR 

271 REM 

280 GOSUB 1300: IF C$ = КСФ THEN GOTO 10: REM CHECK FOR 


ENTRY RESTART 


290 


YY = VAL (СС%): IF YY < О OR YY > 99 THEN 10: REM 


RESTART IF ENTRY IS INVALID 
300 ПТФ = DOTS + "-" + CLS 


au 
390 
391 
400 
410 
420 
108? 
1070 
1091 
1100 
1110 
1120 
1130 
1189 
1190 


REM 
REM DISPLAY ENTRY 

REM 
VTAB (10): HTAR (15): PRINT "ПАТЕ ENTERED: " 
УТАВ (ii): HTAB (20): PRINT DTS 
ЕМІ 

КЕМ 

REM ++ DISFLAY “ІМ” REVERSE-BLANKS ++ 
КЕМ 

INVERSE 

FOR I = 1 TG IW: PRINT " "з: NEXT I 
NORMAL 

RETURN 

REM 

REM ++ ACCEPT ONE CHARACTER INPUT ++ 


Chapter 4: ADVANCED BASIC PROGRAMMING 135 


1191 КЕМ 

1200 GET C$: IF C$ = "" THEN 1200 

1210 IF C$ = КСФ THEN RETURN : REM CHECK FOR RESTART 
1220 IF C$ < "o" GR C$ > "9" THEN GOTO 1200 

1230 PRINT Сөз: КЕМ ECHO KEY'STROKE 

1240 RETURN 


1239 REM 
1290 REM ++ GET А 2-СНАК. INFPLT ++ 
1291 КЕМ 


1300 REM GET 1ST CHARACTER: CHECK FOR RESTART 
1310  GOSLUB 1200: IF C$ = RCS THEN RETURN 

1315 ccs = C$ 

1220 REM GET ZNE CHARACTERS CHECK FoR RESTART 
1330 GOSUB 1200: IF СФ = КСФ THEN RETURN 

13:9 CC$ = CCS + C$ 

1340 RETURN 


Notice that the date is built up in the eight-character string DT$, as month, day, 
and year are entered. 
These three checks are made on data as it is entered: 


1. Is the character a carriage return? 
2. If the character is not a carriage return, is it a valid digit? 


3. Is the two-character combination a valid month for the first entry, a 
valid day for the second entry, or a valid year for the third entry? 


We selected the carriage return as a restart character. By replacing CHR$(13) 
on line 15 you can select any other restart character. When the operator presses 
the selected restart key the entire date entry sequence restarts. We must check 
for the restart character in the one-character input subroutine (at line 1200) and 
again in the two-character input subroutine (at line 1300) since we want to be 
able to restart after the first or second digit has been entered. The main program 
also checks for a restart character in order to branch back to line 10 and restart 
the entire date entry sequence. You could branch directly out of the one-character 
input subroutine to line 10, thereby eliminating the other tests. But it is bad prac- 
tice to exit a subroutine with a GOTO statement instead of a RETURN statement. 
Every subroutine should be treated as a logical module, with specified entry 
point(s) and standard subroutine returns. Branching out of a subroutine any other 
way inevitably leads to tangled programs and ultimately to program errors. 
(Remember that if you do branch out of the subroutine without using a RETURN 
statement, you must use the POP statement to clear the return location.) 

Program logic that tests for nondigit characters resides entirely in the one- 
character input subroutine. We chose to ignore nondigit characters. The state- 
ment on line 1220 tests for nondigit characters. 

Logic to check for valid month, day, and year must exist within the calling pro- 
gram (not the subroutine) since each of these two-character values has different 
allowed limits. 

The statement on line 110 tests for a valid month. 

Statements on lines 130, 140, and 160 compute the maximum allowed day 
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for the entered month. The statement on line 190 checks for a valid day. 

The check for a valid year is very simple; it is on line 290. 

It takes extra time to write a good data entry program that displays information 
in a pleasing manner and checks for valid data input, allowing the operator to 
restart at any time. Is the time worth spending? By all means yes. You will write a 
program once; an operator may have to run the program hundreds or thousands 
of times. Therefore you spend extra programming time once, in order to save 
operators hundreds or thousands of delays. 


FORMS DATA ENTRY 


The following section describes some programming techniques that are best 
implemented in Applesoft. Many of the special effects we use in the example pro- 
gram in this section are difficult or impossible to obtain in Integer BASIC. If you are 
programming exclusively in Integer BASIC, you may still wish to read this section 
since some of the techniques presented in it are adaptable to Integer BASIC. 

The best way of handling multiple-item data entry is to display a form, and then 
fill in the form as data is entered. Consider a name and address. First display a 
form as follows: 


ENTER NAME AND ADDRESS BELOW 
id NAME: 

z] STREET: 

& CITY: 

51 STATE: 

$i ZIP: 


Notice that each entry has been assigned a number. The field numbers appear 
in reverse video on this form. 

The operator enters data sequentially, starting with item 1 and ending with 
item 5. The operator can then change any specific data entry. 

The following program will clear the screen and display the initial form: 


109 REM 

110 REM DISPLAY THE DATA ENTRY FORM 

111 БЕМ 

120 CALL - 936: VTAB 2: REM CLEAR SCREEN АМП POSITION 
CURSOR 


125 PRINT "ENTER NAME AND ADDRESS BELOW" 
130 REM FIRST DISPLAY FIELD NUMBERS 

140 INVERSE 

150 FOR І = 1 TO 4: НТАВ 2: PRINT I: NEXT I 
160 УТАВ 6: НТАВ 29: PRINT 5 

170 NORMAL 

180 КЕМ NOW DISPLAY FIELD NAMES 

190 УТАВ 3: НТАВ 6: PRINT "NAME:" 

200 HTAR 4: PRINT "STREET: " 
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210 НТАВ 6: PRINT "CITY:" 
220 HTAR ©: PRINT "STATE: "; 
230 НТАВ 31: PRINT "ZIFP:" 


As each data item is entered, we will create a reverse field to identify where 
data will appear as it is entered. CrRL-X is used to restart data entry іп the current 
field. The Return key ends data entry in the current field. The following instruction 
sequence provides us with necessary program logic: 


100 ROS = CHRS (24): REM CTRL-X IS THE RESTART CHAR. 
299 REM 
ЛОО REM ENTER ALL 5 FIELDS 


301 REM 
310 FOR F = 1 TO 9: GOSUB 1900: NEXT F 
320 END 


990 REM +44+44444444S5UIBRCUITINE 10004+++++4++4+4+ 

$31 REM ENTER STRING DATA INTO A FIELD WITH LN CHARACTERS 

992 REM THE CURSOR MUST BE IN THE FIELD“S FIRST POSITION 
993 REM THE RETURN KEY WILL END DATA ENTRY 

794 REM THE “LEFT ARROW’ KEY RESTARTS ENTRY 

995 REM NO VALIDITY CHECKS ON ENTERED DATA 

296 КЕМ THE ENTERED STRING IS RETURNED IN CC$ 

297 REM 

1000 HT = FOS (0) + 1: REM REMEMBER START-OF-FIELD 
POSITION 

1010 REM DISPLAY INVERSE VIDEO ENTRY MASE 

1020 INVERSE 

1030 FOR I = 1 TO LN: PRINT " "$3 NEXT I 

1040 NORMAL : HTAB (HT): REM REPOSITION TO START OF FIELD 
1050 КЕМ ENTER DATA 

1060 CC$ = "": REM INITIALIZE QUTPUT TO NULL 

1070 GET C$ 
1080 IF C$ 
ENTRY? 

1090 IF C$ = СНКФ (13) THEN GOTO 1140: КЕМ END OF ENTRY? 

1100 REM WHEN ENTRY IS FULL, WAIT FOR RETURN OR RESTART 

1110 IF LEN (CCS) = LN THEN GOTO 1070 

1120 PRINT ($3: REM ECHO KEYSTROKE 

1130 ССФ = CC$ + СФ: GOTO 1070 

1135 REM ENTRY FINISHED, FILL THE REST OF CCH WITH BLANKS 
1140 J = LEN (Crs) 

1150 FOR I = J TO LN:CC$ = CCS + “ "3 NEXT I 

1160 REM REDISPLAY ENTRY 

1170 НТАВ (НТ): PRINT CC$:: RETURN 

1337 REM +4+4+4+444+4+44+4+S5UBROUTINE 12700++4+44+4++++4+4 

1890 REM BRANCH ТО ENTRY ROUTINE FOR FIELD NUMBER F 

1291 REM 

1700 ОМ F GATO 2000, 2100, 2200, 2200, 2400: RETURN 


RCS THEN  HTAB (НТ): GOTO 1020: REM RESTART 


1989 КЕМ 
1990 REM ENTER 20-СНАК. МАМЕ 
1991 REM 


2000 УТАВ 3: НТАВ 11 
2010 LN = 20: GOSUB 1000:МА% = CCS: RETURN 
2059 REM 
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2090 REM ENTER 20-СНАК STREET 

2091 REM 

2100 VTAB 4: HTAB 11 

2110 LN = 20: GOSUB 1000:CI$ = СС%: RETURN 


2189 КЕМ 
2190 REM ENTER 20-CHAR. CITY 
2191 REM 


2200 VTAB =: HTAR 11 

2210 LN = 20: GOSUB 1000: RETURN 

2289 REM 

2290 REM ENTER 12-CHAR. STATE 

2291 REM 

2300 VTAB 6: НТАВ 11 

2310 LN = 18: GOSUB 1000:57% = CCS: RETURN 


2389 REM 
2390 REM ENTER S-CHAR. ZIP CODE 
2391 REM 


Key in the entire program from statement 100 to statement 2400 and run it. 
Remember if you still have statements 109 through 230 keyed into your com- 
puter from the last example, you do not need to reenter them. 

If your program does not run correctly, check over your listing carefully. In par- 
ticular, look for semicolons in PRINT statements. 

When you run the program, each of the five fields will be highlighted in turn. As 
you enter characters they will echo in the field. When you hit the Return key the 
entire reverse field is replaced by the data you entered. Try using CrRL-X to restart 
data entry. 

Carefully go through the logic of the string entry subroutine, beginning at line 
1000 and ending at line 1170. Before going any further you should clearly under- 
stand this program logic. 

Note how easy it is to see what you are entering, and how simple it is to restart 
any entry to correct errors. 

After the complete name and address has been entered, the program should 
ask the operator if he or she wishes to make any changes; then the program 
should ask which field needs to be changed. А subroutine to ask a yes-or-no 
question appeared earlier in this chapter. We will use a modified version of it, 
where the calling program provides the question to be asked of the operator. Here 
is the complete program with added statements: 


© REM eae te Sb te 3: 3t3€ 3€ 363€ 26 28 IE 3E JEJE H IE GE AE E EHE EIE AE AE GE IE SEE EEE ESE EE Estee 
10 REM THIS PROGRAM DISFLAYS А FORM FOR ENTERING A NAME AND 
11 КЕМ ADDRESS THEN ІТ REQUESTS ENTRY OF THAT DATA 

12 REM ee eee eee PHS ЕЗЕР ЗЕ каты ығы кыла инт 
13 REM 


100 КСФ =  CHR$ (24): REM CTRL-X IS THE RESTART CHAR. 
109 REM 

110 REM DISPLAY THE DATA ENTRY FORM 

111 REM 

120 CALL - 936: VTAB 2: REM CLEAR SCREEN AND POSITION 


CURSOR 
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125 PRINT "ENTER NAME AND ADDRESS BELOW" 

130 REM FIRST DISPLAY FIELI! NUMBERS 

140 INVERSE 

90 FOR I = 1 Та 4: HTAR 2: PRINT I: NEXT І 

160 УТАВ 4: HTAB 29: PRINT = 

170 NORMAL. 

15 REM NOW DISFLAY FIELD NAMES 

1930 VTAB 3: HTAB 6: PRINT "МАМЕ: " 

200 HTAR 4: PRINT "STREET: " 

210 НТАВ 6: FRINT "CITY:" 

220 НТАВ 5: PRINT "ZTATE:": 

230 НТАВ 31: PRINT "ZIPs" 

299 REM 

300 REM ENTER ALL = FIELDS 

301 REM 

310 FOR Е = 1 TO ©: GOSUB 1900: NEXT F 

319 REM 

320 REM ALLOW CHANGES 

321 REM 

330 VTAB 23: HTAR 1: REM GET ENTRY СМ BOTTOM LINE 

340 QUS = "DO YOU WANT TQ MAKE ANY CHANGES? " 

350 GOSUB 1300: REM GET Y/N RESPONSE 

360 IF ҮМ = "N" THEN GOTO 500 

370 VTAB 23: HTAB 1: REM GET ENTRY ON BOTTOM LINE 

330 00% = "ENTER NUMBER OF FIELD TO CHANGE " 

390 LO = 1:HI = 5 

400 GOSUB 1400: REM GET NUMERIC RESPONSE 

410 F = NM: GOSUB 1900: REM CHANGE FIELD F 

420 боОТП S30 

420 REM END ОҒ PROGRAM 

“OO УТАЕ 22: HTAR 1: GOSUR 1200: REM CLEAR BOTTOM LINE 
S10 END 

990 REM tr 4 M -slIBROLTINE 1000-4444 

7971 КЕМ ENTER STRING DATA INTO A FIELD WITH LN CHARACTERS 
99; REM THE CURSOR MUST БЕ IN THE FIELE- = FIRST POSITION 
993 REM THE RETURN KEY WILL END DATA ENTRY 

794 КЕМ THE "LEFT ARROW” KEY RESTARTS ENTRY 

995 КЕМ NO VALIDITY CHECKS ON ENTERED DATA 

79& REM THE ENTERED STRING IS RETURNED IN CCS 

997 REM 

1000 HT = FOS (0) + 1: REM REMEMBER START-OF-FIELD POSITION 
1010 REM DISPLAY (INVERSE VIDEO ENTRY MASK 

1020 INVERSE 

1030 FOR I 1 TO LN: PRINT " "32 NEXT I | 
1040 NORMAL : HTAB (НТ): REM REPOSITION TO START OF FIELD 
1050 КЕМ ENTER IATA 

1060 (Пф = "": REM INITIALIZE GUTPUT TO NULL 

1070 GET C$ 

1080 ТЕ C$ = КСФ THEN НТАВ (НТ): GOTO 1020: REM RESTART 
ENTRY? 

1090 IF C$ = CHR$ (13) THEN GOTO 1140: REM END OF ENTRY? 
1100 REM WHEN ENTRY IS FULL» WAIT FOR RETURN ОК RESTART 
1110 TF LEN (CCS) = LN THEN GOTO 1070 

1120 PRINT C$:: REM ECHO KEYSTROKE 

1130 ССФ = 2% + C$: GOTO 1070 

1135 REM ENTRY FINISHED, FILL THE REST OF CCS WITH BLANKS 
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1140 J = LEN (CC$) 

1150 FOR I = J TO LN:CC$ = CCH + " ": NEXT I 
1160 REM REDISPLAY ENTRY 

1170 HTAB (HT): PRINT CC$s: RETURN 

1189 REM 4+44444+444++4++S5UBROUTINE 12004+4+++4++44++++ 
1199 REM CLEAR ROW WHICH THE CURSOR IS GN 


1191 REM 
1200 НТАВ 1: REM START AT BEGINNING OF ROW 
1210 FOR I = 1 TO 39: PRINT " "s: NEXT I 


1220 НТАВ 1: REM LEAVE CURSOR AT BEGINNING OF ROW 
1230 RETURN 

1289 КЕМ +4444444++4+4SURROUTINE 43004-4404 
1290 REM ASK A QUESTION (00%) AND RETURN А Y OR N RESPONSE 
IN YN$ 

1271 REM 

1300 GOSUIB 1200: REM CLEAR ENTRY LINE 

1310 PRINT 20%; : REM DISPLAY PROMPT 

1220 GET YN$: IF YN$ < > "М" AND YN$ < > "Y" THEN GOTO 
1320 

1330 PRINT YN$3: REM ECHO RESPONSE 

1340  RETLIRN 

1289 REM tt 9-SUBROLITINE 1400+4++++4+4+4++4++ 
1:320 REM ASK FOR NUMERIC ENTRY (PROMPT IS lis) 
1371 REM RETURN RESPONSE IN NM 

1392 REM NM MUST BE <=HI AND >=LO 

139% REM UU 

1400 GOSUB 1200: REM CLEAR ENTRY LINE 

1410 PRINT QU$:: REM DISPLAY PROMPT 

1420 GET C$:NM = VAL (C$) 

1425 REM CHECK THAT ENTRY 15 WITHIN RANGE 

1430 IF NM «€ LG OR NM > HI THEN GOTO 1420 

1440: PRINT C$:: REM ECHO RESPONSE 

1450 RETURN 

1889 REM 444444444+4++SUBROUTINE 197004+4+4+44+4+4++4++4+4 
1890 REM BRANCH TO ENTRY ROUTINE FOR FIELD NUMBER F 
1891 КЕМ 

1900 ON F GATO 2000, 2100, 2200, 2300; 2400: RETURN 
1989 REM 

1990 REM ENTER 20-CHAR. NAME 

1791 REM 

7000 VTAB 3: HTAR 11 

2010 LN = 20: GOSUB 1000:МА% = 12%: RETURN 

2089 REM 

2090 REM ENTER 20-CHAR STREET 

2091 КЕМ 

2100 VTAB 4: HTAB 11 

2110 LN = 20: GOSUB 1000: CI$ = CC$: RETURN 


2189 REM 

2190 REM ENTER 20-CHAR. CITY 
2191 REM 

2200 VTAB 5: HTAR 11 

2210 LN = 20: GOSUB 1000: RETURN 
2289 REM 

2290 REM ENTER 17-CHAR. STATE 
2291 REM 


ОО VTAR 6: НТАВ 11 
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2310 LN = 17: GOSUB 1000:ST$ = СС%: RETURN 
2289 REM 

2290 REM ENTER 5-СНАК. ZIF CODE 

2291 REM 

2400 УТАВ 6: НТАВ 35 

2410 LN = 5: GOSUB 1000:Z21$ = CC$: RETURN 


You should study the name and address program carefully-and understand the 
data entry aids which have been included. They are: 


1. 


By labeling each field апа juxtaposing a reverse video entry mask at 
the appropriate time, you clearly indicate to the operator what data is 
expected, and how many entry spaces are available. 


. When an operator enters the number of a field to change, the reverse 


field mask again quickly tells the operator whether the correct field 
number was specified. 


. An operator does not have to fill in all the characters of a field; when 


the operator presses the Return key the balance of the field is filled 
out with blank characters. 


. Atany time the operator can restart entry in a field with CrRL-X. 
. When the program asks questions, only meahingful character 


responses are recognized: Y ог М for “yes” and "no," or à number 
between 1 and 5 to select a field. It is bad practice to allow any entry 
other than a meaningful one. For example, to recognize Y for ''yes" 
and any other character for “по” could be disastrous, since 
accidentally tapping a key could take the operator out of the current 
data entry prematurely. Conversely, recognizing М for “по” and any 
other character for “yes” would cause the operator to unnecessarily 
reenter data into some field, just because the operator accidentally 
touched the wrong key. 


These are data entry features which we have not included but could add: 


1. 


2. 


Check the ZIP code for any nondigit entry. (Note that similar codes in 
some countries do allow alphanumeric entries.) 

Many cautious programmers will ask the question ARE YOU SURE? 
when an operator answers NO in response to the question DO YOU 
WANT TO MAKE ANY CHANGES? This gives the operator a second 
chance in the event that she or he accidentally touched the wrong key. 


. Provide an additional key which aborts a current data entry and 


restores the prior value. For example, if the operator chooses the 
wrong field to change, the example program forces the operator to 
reenter the field. The program could easily recognize a key which 
aborts the current data entry and retains the previous entry. 


. Enable the — key for use as a backspace key. Each time the — key is 


pressed, the cursor backs up one space and the last-entered character 
is replaced by an entry mask character (reverse video) on the display 
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screen and by a blank character in the subroutine output string (CC$). 
Of course there can be no backspace when the cursor is at the left 
edge of the entry field. 


Try modifying the name and address entry program yourself to include the 
additional safety features described above. 


FORMATTING OUTPUT 


When you turn on an Apple ll computer, output automatically goes to the display 
screen. There are statements which will send the output to a printer or any other 
device capable of receiving output. 

There are a number of differences in programming output to a screen display 
as compared to a printer. For example, the printer may be wider than the display, 
in which case output which will fit on a printed line would run over the display line. 
On the other hand, HTAB and VTAB (TAB in Integer BASIC) can be used to move 
the cursor around the screen display, but they cannot be used to move a print 
head around on a piece of paper. 

There are also many similarities in the programming techniques used to create 
printer and display screen output. Most of the discussion that follows applies to 
both. Any that applies only to display screens is noted. If you are planning to write 
programs that output to a printer you should also read the discussion of printer 
programming given later in this chapter. 

Programming output is much simpler than programming data entry, since there 
is no operator interaction to worry about. You must make sure that the informa- 
tion is easy to use, and that is all. Here are a few rules to follow: 


1. Avoid crowding too much information into a very small space. 


2. If numbers or character strings are listed in columns, align the data so 
that the eye can quickly run down the column. 


3. Use reverse fields to highlight key information, top headings, and side 
headings (display screen only). 


Below are some hints that will help you avoid unnecessary errors when pro- 
gramming output. 


1. Remember to follow individual items in a PRINT statement with a 
semicolon unless you specifically want the spacing provided by 
commas. This is the most common source of errors in output 
programming. 

2. Before doing anything else, design your display screen or report. Use a 
piece of graph paper or a form made specifically for report or display 
design. Appendix L has a display screen that will allow you to compute 
rows and columns accurately. The alternative to advance planning is 
trial and error, which in the end will take a lot more time than drawing 
the display or report first. 
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3. Watch for array subscripts which do not divide evenly into columns. 
For example, suppose you have 25 items in array N$(1) which you are 
printing in three columns. You might be tempted to do something like 
this: 


ТОО FOR I = 1 TO 25 STEP З 
200 REM PROCESS COLUMN 1 


300 REM PROCESS COLUMN 2 


400 REM PROCESS COLUMN 3 


500 NEXT | 


But on the final pass of the FOR-NEXT loop, indexes 26 and 27 will be 
computed, although they do not exist. You can easily check for the 
end of an array in a FOR-NEXT loop as follows: 


100 FOR I z LO TO HI STEP ST 


. 


350і-і-1 
360 IF | > HI THEN 510 


500 NEXT 
510 REM CONTINUE WITH PROGRAM 


The Display Screen as a Data Window 


When dealing with large quantities of data, a very common technique is to use the 
display screen as a window on the data. At any time the display screen shows only 
part of the data available. One way of doing this is to group the data into pages, 
each of which will fit on the display screen. Programs that use this technique must 
have separate routines to display the field headings and data values for each page. 
They must also provide some means by which the program user can switch from 
one page to another. 

Very often arrays are used to hold large amounts of data. In this case, you can 
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use the display screen like the viewfinder of a camera. Imagine that the array data 
is written on a large chalkboard and you are looking at the chalkboard through the 
viewfinder of a camera. The chalkboard is large enough that you cannot get it all 
in the viewfinder at one time, but you can view any part of the chalkboard by mov- 
ing the viewfinder up, down, right, or left. The display screen can imitate this. 
We will illustrate the use of the display screen as a data window by creating an 
example in Applesoft of the viewfinder technique just described. To begin, we will 
create a two-dimension integer array. As the value of each array element, we will 
assign a four-digit number which identifies the array indexes, as follows: 


X%(i,/)=0/0/ 
For example: 
X%(3,2)=0302 
X%(19,8)=1908 
X%(11,12)=1112 
We can initialize this integer array very simply, as follows: 


10 DIM X%(14,50) 

20 FOR I = 1 TO 14 

30 FOR J = 1 TO 80 

40 XZ(1I,4) = I # 100 + J 
50 NEXT J 7 

60 NEXT I 


Now we will display a portion of this array. We will use the top two rows of the 
display for top heading, and the first nine spaces of each line for side headings, as 
follows: 
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The actual column numbers will appear where you see XX above. The actual 
row numbers will appear where you see YY. Here are the necessary program 
statements to create row and column headings in reverse video: 


1000  INVERSE 

1020 FOR I = 1 TO 3 

1030 HTAR 4 + I * 10: PRINT "COLUMN" ; 

1040 NEXT I 

1050 PRINT 

1060 FOR I = о Та Z2 

1065 КЕМ 1 EXTRA SPACE AHEAD OF 1-BIGIT NOS. 
1070 5% = 0: IF C% + I € 10 THEN 3% = 1 

1080 HTAB 18 + I # 10: PRINT SPCC SX):UCX + I; 
1090 NEXT T 

1100 PRINT 

1110 FOR I = КУ TO RY + FY 

1115 REM 1 EXTRA SPACE AHEAD OF 1-ПГІСІТ NOs. 
1120 5% = О: IF I < 10 THEN 57 гі 

1120 HTAB 4: PRINT "ROW"s: HTAR 8: PRINT SPCC 59931 
1140 NEXT I 

1150 NORMAL : RETURN 


We deliberately created a window that is smaller than the entire screen so 
that we can better illustrate the concept of a window on data. There is nothing to 
stop you creating a window that occupies your entire screen; however there will 
be occasions when you want a small window so that other data can appear on the 
screen concurrently. 

We will now add instructions that ask the operator to enter two numbers repre- 
senting the smallest column and row of the array. The array element with this col- 
umn and row number will appear in the top lefthand display position. The display 
window will be filled with array elements from adjacent columns and rows, up to 
the end of the window. Here is the complete program: 


= КЕМ WINDOW AN A TABLE DISPLAY FROGRAM 

5 КЕМ HE EES EEE EEE EH EEE EAE 
10 HOME : FRINT "PLEASE WAIT...INITIALIZATION IN PROCESS" 
20 DIM X%(14,50) 

ЗО FOR I = 1 TO 14 

40 FOR М = 1 TO So 

по XZCCI,.1) = I # 100 + d 


60 NEXT J 
70 NEXT I 
73 HOME 


SO HTAR 1: УТАВ 20: INFUT "ENTER COLUMN (1 TO 12): "307% 
90 IF CZ < 1 ОК C% > 12 THEN GOTO So 

100 УТАВ 21: INFLT "ENTER ROW (1 TO 419: "367 

110 IF R4 < 1 OR RZ > 41 THEN GOTO 100 

120 УТАВ 1: HTAR 1: GOSUB 1000: REM DISPLAY HEADINGS 
130 REM FILL IN WINDOW VALUES 

125 VTAR 3 

140 FOR I = КУ TO RAZA + 9 

150 HTAR 10 

160 FOR J= CZ TO CX + 2 

165 REM DISPLAY RIGHT-JUSTIFIED VALUES IN WINDOW 
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170 X$ = STR$ (ХУ(0.Ь1)): PRINT SPCC 10 — LEN (X$))3X%3 
180 NEXT 4 

190 РКІМТ : REM NEXT DISPLAY LINE 

200 NEXT I 

210 УТАВ 22: PRINT "CONTINUE? ENTER Y OR N "; 

220 БЕТ C$: IF C$ < > "Y" AND C$ < > "М" THEN 220 


220 IF c$ "Y" THEN GOTO ао 
240 END 
990 REM 


991 REM +444+4++4+SUIBROUTINE 1000-44 
992 REM DISPLAY ROW AND COLUMN HEADINGS 
1000 INVERSE 
1020 FOR I = 1 TO 3 
1030 НТАЕ 4 + I # 10: PRINT “COLUMN"S 
1040 NEXT I 
1050 PRINT 
1040 FOR I = 0 Ta 2 
1065 КЕМ 1 EXTRA SPACE AHEAD OF 1-ПІСІТ NOS. 
1070 S% = 0: IF CZ + I < 10 THEN 57 = 1 
1080 HTAB 18 + I # 10: PRINT SPCC S4)0:C^ + Із 
1090 NEXT I 
1100  FRINT 
1110 FOR J = RZ TURA + 9 
. 1115 REM 1 EXTRA SPACE AHEAD OF 1-DIGIT NOS. 
1120 S% = O: IF I < 10 THEN SZ = 1 
1130 НТАВ 4: PRINT "RüW"s: HTAB S8: PRINT  SPC(C SZ)3:I 
1140 NEXT I 
1150 NORMAL : RETURN 


Enter this program into the computer and run it. If you enter the program cor- 
rectly, the first thing you will notice is that the computer stops and appears to do 
nothing for a while; it is executing the nested FOR-NEXT statements occurring on 
lines 30 through 70. It takes five or ten seconds to fill array X% with numbers. The 
program displays an advisory message about the initialization. Without such a 
message, the program user may well assume that the computer is not working. It 
is a good idea to display a prominent message whenever such periods of apparent 
inactivity occur. 

Note that column numbers from 1 through 12 are allowed. There are three col- 
umns, therefore any column number up to 12 will stay within the array dimension 
of 14 columns. Row numbers from 1 to 41 are allowed, since ten column num- 
bers starting with 41 would run through 50, which is the other array dimension. 

The integer value from array X96 is converted into a string on line 170 before 
being printed. We made this conversion to simplify display formatting. It is then 
easy to compute the number of spaces between columns, as shown by the PRINT 
statement on line 170. It is not so easy to align numeric values correctly when dis- 
playing them directly. To see this for yourself, change line 170 as follows: 


170 PRINT SPC «7»; Х% «J, I>; 


Numbers will align providing you do not display any four-digit numbers — at 
which time the display will be too wide for a 40-character screen. 
Our program takes great care to terminate the display on the 39th column of 
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the display, rather than the 4Oth and last column. If you run displays out to the 
40th column, you will run afoul of the wrap-around logic whereby lines that are 
more than 40 characters long automatically continue on the next line. You are 
best off not tangling with the display formatting nightmare that can result from 
the interaction between carriage returns generated by printing in column 40 and 
your own formatting carriage returns. 

As an exercise, it is worth modifying the complete table display program so 
that it does go out to the 40th column. To do this you must change the horizontal 
tab on line 150 from 10 1011, оп line 1030 from 4+1 #10 to 5 +1 #10, online 1080 
from 18-1410 to 19--1410, and finally on line 1130 from 4 and 8 to 5 and 9. Now 
try running the program; the columns of numbers line up, but you have too many 
carriage returns and the column numbers in the top headings are covered by the 
first row of array values. See if you can eliminate the extra carriage returns and 
generate the correct display. This is not an easy programming task. 

Notice that the statements which ask for input on lines 80, 100, and 220 
are all followed by program steps that don't allow invalid inputs. Even in this sim- 
ple demonstration program we take the time to program safe input. 

A useful refinement to a program that displays a window on an array is to pro- 
vide the operator with means of moving the window up or down one row, or right 
or left one column. This is easily done. We will use the I, J, K, and M keys for 
directional control in much the same manner as they are used in edit mode (de- 
scribed in Chapter 3). The І key moves up one row, M down one row, J left one 
column, and K right one column as shown below. 


EEEBEERLLITELTIIS 
CIETE 
ELLLIELEELUIE 


LIHIILEEAIES 


To accomplish this task we must replace lines 210 through 240 with the 
following statements: 


210 УТАВ 22: FRINT "CONTINUE?" 

215 PRINT "ENTER DIRECTION (1,.15К.М)» Y: OR N "3 
z20 GET C$ 

225 REM DOWN ONE ROW? 


230 IF RX > 1 THEN IF C$ = "M" THEN КУ = RZ - 1: GOTO 120 
225 REM UP ONE ROW? 
240 IF RZ < 41 THEN IF C$ = "I" THEN RA = RZ + 1: GOTO 120 


245 REM LEFT ONE COLUMN? 
250 IF CZ > 1 THEN IF C$ = "JI" THEN CZ = CA - 1: GOTO 120 
259 REM RIGHT üNE COLUMN? 
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12 THEN IF C$ = "К" THEN CX = CX + 1: GOTO 120 
270 IF C$ "Y" THEN GOTO 80: REM ENTER NEW ROW AND COLUMN 
230 IF C$ "N" THEN END 

235 REM SOUND BELL AND REJECT ANY OTHER ENTRY 

290 PRINT СНК% (79%: GOTO 220 


260 IF CX 


ІП. 


Notice how straightforward the logic is, even though we are still checking for 
operator errors. Any entry other than one of the six allowed characters is rejected, 
and a directional control character is rejected if it would move the window past 
the edge of the array dimensions. 


PROGRAMMING PRINTERS 


The Apple ІІ treats the printer as a substitute for the screen display. In order to 
create printer output, therefore, you must include program statements that 
deflect output from the display to the printer. Output must be deflected back to 
the display when you have finished printing. This is done using the PR# state- 
ment. 

Printers connect to computers via a serial or parallel interface, depending on 
the printer. 

Normally, serial interface cards are inserted in slot 1 of an Apple Il computer, 
while parallel interface cards are inserted in slot 2. But this is a convention rather 
than a necessity. In fact, serial and parallel interface cards can be inserted in any 
slot (other than slot O). 


Outputting Text 
to a Printer 


You may recall that PR# is considered a DOS statement whenever DOS is pres- 
ent. This means it must be printed with a prefix character of CrnL.-D (ASCII code 
4). The program below will print two lines of text on a printer connected to an 
interface card in slot 1 of an Apple Il computer with DOS present: 


10 REM  OLITFLIT TWO LINES OF TEXT TO А PRINTER 

20 REM CREATE А CTRL-D CHARACTER 

зо Пф-"" 

40 REM SELECT THE SERIAL 1/0 FORT 

30 PRINT D$:"PR41" 

ФО PRINT "Та A SCREEN OR THE PRINTER AN AFFLE WILL WRITE" 
70 PRINT “AND IN EACH CASE THE DATA GOES OUT BYTE BY BYTE" 
SO КЕМ  DESELECT THE. PRINTER 

ЭО PRINT D$: "PR4 Oo" 

100 END 


The statement on line 30 creates the control character which converts the PR 
command into a BASIC statement. PR# statements appear on lines БО and 90. 
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Тһе statement on line 50 deflects output from the screen to the printer, whereas 
the statement on line 90 deflects output back to the screen. The PRINT state- 
ments on lines 60 and 70 output two lines of text to the printer. Here is the output 
created when the program is run: 


TO THE SCREEN OR А FRINTER THE APPLE WILL WRITE 
AND IN EACH CASE THE DATA GOES OUT BYTE BY BYTE 


Here is the same program for an Apple ІІ with DOS absent: 


10 REM OUTPUT ТИС LINES GF TEXT TG A PRINTER 

40 КЕМ SELECT THE SERIAL I/0 PORT 

SO PRINT "PR#1" 

60 PRINT "TO A SCREEN OR THE PRINTER AN AFPLE WILL. WRITE" 
70 PRINT “AND IN EACH CASE THE DATA GOES OUT BYTE BY BYTE" 
ЗО REM DESELECT THE PRINTER 

"OQ PRINT "PR#O" 

100 ЕМІ 


Programmable Printers 


Many printers allow output to be formatted under program control. By including 
appropriate control characters in the text data stream going out to the printer, you 
can adjust line lengths, character set, page length, and a variety of other printed 
page characteristics. 

A variety of popular printers are commonly used with Apple ІІ computers. From 
a programming viewpoint, however, the Apple ll treats all printers identically. For 
example, suppose a Texas Instruments model 810 printer is connected to an 
Apple computer via a serial interface in slot 1. The Texas Instruments manual says 
we can set the page size to six lines per page with this character sequence: 


Esc-2 Crn.-I RETURN 
—— ee” N ee” | 


| L Terminating carriage return 
Page size: six lines of text plus 
three top-of-form lines 


These characters tell the Texas 
Instruments printer a page size 
definition follows 


In addition, we can force the printer to advance to the top of the next page (this is 
called a form feed) with this character sequence: 


Crat-R RETURN 
we ee 


| t Terminating carriage return 
This character tells the Texas Instruments 


printer to do a form feed 


150 APPLE Il USER'S GUIDE 


Modifying our earlier printer program, the Applesoft listing below outputs the 
same two lines of text 15 times, in six-line blocks. The program shown is for use 
with DOS present. 


10 REM  CULTPLT TEXT TO THE PRINTER 
11 REM USING 6 LINES PER PAGE AND 5 PAGES 

20 REM CREATE А CTRL-D CHARACTER 

30 D$ = "* 

40 REM SELECT THE SERIAL 1/0 PORT 

SO PRINT D$; "PRH" 

51 КЕМ SELECT 6 LINES PER PAGE 

82 PRINT CHR$ (27)3"2"3 CHR$ (4) 

53 PRINT CHR$ (12):: REM PRINT FORM FEED TO POSITION FOR 
START OF OUTPUT 

54 FOR I = 1 TO 15 

&0 PRINT "TO А SCREEN OR THE PRINTER AN APPLE WILL WRITE" 

70 PRINT "AND IN EACH CASE THE DATA GOES QUT BYTE BY BYTE" 

75 NEXT I 

&O REM — DESELECT THE PRINTER 

90 PRINT D$s"PR&O" 

100 END 


In the program above, the statement on line 52 selects six lines per page. The 
CHR$(27) function represents the Esc character. CHR$(9) defines a page as being 
six lines plus three lines which separate the bottom of one page from the top of 
the next. The semicolons concatenate the three characters to give the required 
character stream. 

The statement on line 53 executes the top of form. The CHR$(12) function is 
the form feed character. A semicolon follows the form feed character since with- 
out it the PRINT statement would produce a carriage return, and that would result 
in a blank line. Without the semicolon, therefore, the first page would have one 
blank line and five printed lines on it, while subsequent pages would have six 
printed lines per page. 

Any other programmable printer options are enacted by outputting other 
appropriate nonprinting contro/ codes in the same way. 

This program will not work in Integer BASIC because it uses the CHR$ func- 
tion. You can generate almost any string value by pressing some key or combina- 
tion of keys, though. So you can replace CHR$ with a pair of quotation marks 
enclosing a non-printing keystroke. For example, the string value generated by 
entering (as three keystrokes) “Ес” is the same as CHR$(27). See Appendix | for 
a complete list of such equivalents. 


Printing Program Listings 


If you type the LIST command at the keyboard, any program in the Apple Il 
memory will be listed at the display. To print the listing instead, enter appropriate 
РАЗ commands before and after issuing the LIST command. Assuming that the 
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printer is connected to an interface card in slot 1, here are the required steps: 


1. Make sure that the program to be listed is is the Apple Il memory. 


2. With the cursor on a blank screen line, select the printer by typing 
PR+1. The cursor will return to the first character of the current line 
but will not drop down to the next display line. 


3. Now type LIST. This command will not appear on the screen, but it will 
show up on the printer along with a printout of the program to be 
listed. 


4. When the entire program has been listed, return output to the display 
screen by typing PR#0. This command will not appear on the display 
screen; it may appear on the printer. 


STORING DATA ON CASSETTE 


We learned in the last chapter how to save and load programs on the cassette 
tape. In Applesoft, you can also record numeric and integer arrays on cassette 
tape. 

The STORE instruction records array values and the RECALL instruction reads 
them back in. Neither statement controls tape movement, nor do they display 
directives telling the program user when to operate the cassette recorder buttons. 
The program below demonstrates the use of STORE and RECALL. It assigns 
values to a numeric array, stores the array on a cassette tape, then sets all the 
array values to zero, and finally recalls the array values from the tape. The array 
values are displayed at key points to document the changes that occur as the pro- 
gram progresses. 


10 REM THIS PROGRAM DEMONSTRATES STORE ANI! RECALL 

20 КЕМ ESE IEE REESE IEEE TE TETE TE 3E 3E 2E каған HE ЗЕ GE 3E EIE IE IE IE EIE SEE GE SERE 

30 DIM AC10) 

40 HOME 

О PRINT TABC 4)3"STORED"s TABC 13): "CLEARED": TAB 229: 
"RECALLED" 

60 REM INITIALIZE ARRAY VALUES 

70 FOR І = 1 TO 10:601) = I: NEXT I 

80 T = 8: GOSUB 1000: REM DISPLAY VALUES ТО BE STORED 

970 VTAB 20: НТАВ 1 

100 PRINT "FLACE CASSETTE IN RECORDER. REWIND IT." 

110 PRINT "PRESS THE “RECORD” AND “PLAY” BUTTONS," 

120 INPUT "AND ENTER "GO "C$ 

130 IF C$ < > "GO" THEN GOTO 30 

140 STORE А 

160 CLEAR = REM SET ARRAY VALUES TO ZERO 

170 УТАВ 2:T = 18: GOSUB 1000: REM DISPLAY CLEARED ARRAY 
180 VTAB 20: НТАВ 1 

190  GOSUB 1100: REM ERASE LAST INSTRUCTIONS 

200 VTAB 20: HTAB 1 

210 PRINT “REWIND ТАРЕ. FRESS “PLAY” BLITTON, " 
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220 INPUT "AND ENTER “GO” "sC$ 

230 IF C$ < > "GO" THEN GOTO 200 

240 RECALL A 

260 УТАВ 2:T = 28: GOSUB 1000: REM DISPLAY RECALLED VALUES 
255 УТАВ 20: HTAB 1 

270 GOSUB 1100: REM ERASE LAST INSTRUCTIONS 

280 УТАВ 20: HTAB 1 

290 PRINT "PRESS ^STOP^ BUTTON." 

300 END 

990 REM +4444444+44444SLIBROLITINE 1000+444+4+4+4+4+444+4+4+4+ 

991 REM DISPLAY VALUES OF ARRAY A 

1000 FOR I = 1 TO 10: HTAB T: PRINT ACI): NEXT I: RETURN 
1090 REM 4¢44+444+4++4+4+4++4++5UBROUTINE 1100++++++++++++++++++++ 
1091 REM ERASE THREE DISPLAY LINES 

1100 FOR І = 1 TO 119: PRINT " "s: NEXT I: RETURN 


You can store an array under one variable name and recall it using a different 
variable name. But generally speaking, the dimensions of the array you store with 
must be the same as the dimensions of the array you recall with. There are some 
complicated exceptions which are covered in Chapter 8. Unless you are 
specifically trying to achieve some special effects, use RECALL with data from 
any given cassette using an array with the same dimensions as the one you used 
STORE with. 


PROGRAM OPTIMIZATION 


Traditionally, the optimal program is the one that, for a given task, runs the fastest 
and uses the least memory. Of course this dual goal must be moderated so that 
the resulting program is still reliable, easy to write, easy to use, easy to read, and 
easy to change. You will benefit more in the long run by spending your time 
directly on these aspects of your programs instead of tweaking programs for 
maximum speed and minimum memory requirements. Still, if you know how to 
optimize program speed and memory usage, you can initially write programs that 
are efficient and don't need any fine tuning after they're running. In this spirit, we 
present a few ways to write programs that are faster and use less memory. 

Some of the techniques for making a program run faster will make it take more 
space, while some ways of decreasing space requirements will increase program 
execution time. You will have to decide which is more important in your particular 
program. 


FASTER PROGRAMS 


Avoid using constants (e.g., О, 100, “Y”, "ENTER"'). Instead, assign the value of 
the constant to a variable early in your program. Then use the variable where you 
would have used the constant. This is especially important when you are 
repeatedly using constant integer values in real expressions. It takes longer to con- 
vert a constant to a real value than it does to look up the value of a variable. And 
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when such a conversion takes place inside a FOR-NEXT loop, an often-used 
subroutine, or a user-defined function, the difference becomes that much more 
significant. This technique has the added benefit of making your program 
easier to change. If you should ever need to change the constant, it will be easier 
to change the one assignment statement than to hunt down and change every 
occurrence of the constant. 

Use those variables that are referenced often in a program as early in the pro- 
gram execution as possible. Memory space for variables is allocated on a first 
come, first serve basis. BASIC will find a variable at the front of the list faster than 
one at the end of the list. 

When BASIC encounters an instruction to branch to another line number, it 
starts looking for that line number at the beginning of the program and searches 
sequentially through the program until it finds it. Clearly, the lower a line number is 
in relation to the rest of the lines in the program, the faster BASIC can branch to it. 
Therefore, assign the lowest line numbers in your program to the most often-used 
subroutines. 

In Applesoft, do not include index variables with NEXT statements. That way, 
Applesoft does not have to verify whether you specified the correct index. 


COMPACT PROGRAMS 


Use subroutines to avoid duplicate programming for identical logic. This will also 
go a long way towards improving the readability, reliability, and changeability of 
your program. 

Use the zero elements of arrays (e.g., X(O), B(O)). 

There are fewer characters in a short variable name than there are in a constant 
value that has many digits. So assign constant values to variable names and use 
the variable names in place of the constant values. 

Put more than one statement on a program line. It takes an extra five bytes of 
memory for each extra program line. Note however that compound program lines 
are hard to edit and harder yet to read and understand. Figuring out how to make 
the program work the first time is bad enough; it's even worse to have to do it 
time and time again. 

Use REM statements judiciously; abbreviate comments. But be careful; the 
fewer remarks your program has, the harder it will be to understand when you 
come back to it later on. 

Be thrifty with the use of variables. Each variable requires a certain amount of 
memory, even if you only use it once. So establish a system of assigning variable 
names that includes some scratch variables which can be used for FOR-NEXT 
loops, intermediate calculations, and the like. Don't overdo it though; your pro- 
gram will be easier to understand if you assign variables in a meaningful way. Es- 
tablish standard identities for individual variables (e.g., CN$ is the customer name) 
and groups of variables (e.g., all scratch variables start with X). 

Use INPUT statements and data files (if you have a disk drive; see Chapter 5) 
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instead of assignment statements and DATA statements. 

In Applesoft, use integer arrays instead of real arrays. Each integer array value 
takes two bytes of memory, while real array values require five bytes each. Use 
the FRE function periodically in your program to clean up the string storage area 
of memory. 


DEBUGGING 


А new program never seems to work quite the way you expect it to. Even if there 
are no errors in the BASIC syntax, there are likely to be errors in the program logic. 
Either kind of error is a bug. The process of finding and eliminating program errors 
is called debugging. There are several approaches you can take to debugging a 
program. 

This is an appropriate place for the usual caveat: take your time, plan it out, get 
it right the first time. Don't sit down at the keyboard with a half-baked notion 
about what you want your program to do and start hacking away. If you are new 
to programming, supplement this book with one of the BASIC primers listed in 
Appendix K to get some pointers on good programming practices. 

If you have written your program and it doesn't seem to be working right and 
you can't figure out why, there are some BASIC statements you can use that will 
help you debug your program. 


The PRINT Statement 


Surprisingly, the plain old PRINT statement is a very useful debugging tool. You 
can temporarily put extra PRINT statements in your program at strategic points to 
display messages to tell you that the program has reached a certain point without 
failing, and to print out intermediate values of variables. This way you can trace 
the flow of program execution and you can check the results of intermediate 
calculations. 


The TRACE Statement 


The TRACE statement lives up to its name; it traces the flow of program execu- 
tion by displaying the line number of each statement as it is executed. To see how 
it works, type in the following program, then type TRACE followed by RUN. 


100 FRINT "ENTER А NUMBER FROM 1 TO 5 (6 TG END)"; 
110  INPUT N 


120 IF М = 1 THEN PRINT "UNO"; 
130 IF N = 2 THEN PRINT "005"; 
140 IF N = 3 THEN PRINT "TRES"; 
150 IF N = 4 THEN PRINT "CUATRO"; 
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160 IF М = & THEN PRINT "CINCO"; 
170 IF N > 5 THEN GüOTO 100 

180 FOR I= 1 TON 

190 PRINT " #"3 REM PRINT М ASTERISKS 
200 NEXT I 

210 CALL - 936: REM CLEAR SCREEN 

220 GATO 100 


To cancel TRACE mode and return to normal, execute the statement NO 
TRACE. 


The DSP Statement 


There is another useful debugging statement available only in Integer BASIC: the 
DSP statement. Here is an example: 


210 ГЕР COUNT 


Once this particular DSP statement has been executed, the Apple Il will notify you 
each time the value of variable COUNT changes, and on which line number the 
change occurred. Since the RUN command disables any previously executed DSP 
statements, you must use GOTO to start the program, or put your DSP state- 
ments on program lines. 

You can also turn off DSP mode for a variable with a NO DSP statement. Here 
is an example: 


2300 NODSF NAMES 


Once this statement has been executed, the Apple ІІ ceases to notify you each 
time the value variable NAME$ changes. 

Try adding the following lines to the example we used with TRACE to see the 
effect of DSP. Although you can use both TRACE and DSP simultaneously, try 
running the example program without TRACE to more clearly see the effects of 
DSP. 


10 ПЕРМ 

20 DSPI 

100 PRINT “ENTER А NUMBER FROM 1 TO 5 (6 TO END) "5 
110 INPUT М 


120 IF N = 1 THEN РКІМТ "ИМА": 
130 IF N = 2 THEN PRINT "005"; 
140 IF М№ = 3 THEN PRINT "TRES"; 
150 IF М = 4 THEN PRINT "CHUATRO"S 
160 IF М = & THEN PRINT "CINCO"; 
170 IF N 5 THEN GOTO 100 


180 FOR i = 1 TAN 

190 PRINT " +": REM PRINT М ASTERISKS 
200 NEXT I 

210 CALL - 936: REM CLEAR SCREEN 

215 NODSPN 

220 GOTO 100 
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IMMEDIATE AND PROGRAMMED 
MODE RESTRICTIONS 


You can use most BASIC statements in deferred mode or as commands in 
immediate mode. There are some statements that are legal only in deferred mode, 
and others that are legal only in immediate mode. Table 4-2 lists the restricted 
statements for Integer BASIC. Table 4-3 lists the restricted statements for 
Applesoft. 


TABLE 4-2. Integer BASIC Statements Restricted to 
Immediate or Deferred Mode 


Deferred Mode Only Immediate Mode Only 


END 
FOR 
GOSUB 
INPUT 
NEXT 


RETURN 


TABLE 4-3. Applesoft BASIC Statements Restricted to 
Immediate Mode 


ON ERR GOTO 
RESUME 


5 


The Disk Il 


The disk drive is one of the most important components of a computer system. 
Disk drives allow almost instantaneous access to any item in a large block of 
information. The Apple Disk Il can store more than 100,000 characters of data on 
a single diskette. That is over twice the amount that can be stored in 48K of RAM, 
and when the computer is turned off, all of the information stored on a diskette 
remains intact. 


ABOUT DISKS 


Disks store information magnetically, the same way a tape recorder does. The 
‘biggest difference is that a disk is round, like a record. It spins like a record too. 
Inside the disk drive there is a head which can read and write information. The 
computer can move the head to any location on the surface of the disk. This 
ability is called random access. Thus, the disk is a random access storage device. А 
special program, called the Disk Operating System, or DOS, controls all the opera- 
tions of the disk. There are several different kinds of disks. 


Hard Disks 


Hard disks are rigid, and coated with a magnetic substance. Hard disks typically 
store 5 or 10 megabytes of data (a megabyte equals one million bytes). Most hard 
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FIGURE 5-1. Typical Hard Disk System oto courtesy of Cameo Electronics 


disks are removable; that is, the disk and the drive are separate, so you can 
change disks. Hard disks cost about $150.00 each; hard disk drives cost $3,000 
to $10,000. Figure 5-1 shows a typical hard disk system. 


Winchester Disks 


Winchester disk drives, pictured in Figure 5-2, use a special technology that 
allows six to ten times more data to be stored on each disk. Winchester disks are 
extremely susceptible to dust and dirt — even cigarette smoke. Because they 
must be kept very clean, Winchester disks are sealed inside the disk drive and 
cannot be changed. Winchester disk systems cost from $2,500 to $8,000. 


Diskettes 


Diskettes are the most popular type of disk. A diskette consists of a circular vinyl 
disk enclosed in a rigid plastic envelope. The envelope protects the diskette from 
damage during normal handling and use. The diskette spins freely inside the 
envelope. Openings in the envelope allow the head access to the surface of the 
diskette and provide an area where the drive can grip and spin the diskette. The 
diskette should never be removed from its envelope. Figure 5-3 shows what a 
diskette looks like outside its envelope. 
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Photo courtesy of Corvus Systems, Inc 


FIGURE 5-2. Winchester Disk Drive 


FIGURE 5-3. Diskette Without Protective Envelope 
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FIGURE 5-4. 8-inch and 5-1/4-inch Diskettes 


Diskettes, also known as floppy disks, come in two sizes: 8-inch diameter and 
5-1/4-inch diameter, both illustrated in Figure 5-4. Apple Disk Il uses 5-1/4-inch 
diskettes, which are also called mini-disks or mini-diskettes. The Disk Il can store 
over 100,000 bytes on each diskette. “жаа 


HOW DATA IS STORED ОМ DISKS 


You should be familiar with the various facets of the disk storage process. Infor- 
mation stored on a disk is the result of many coordinated actions. 


Tracks 


To find one particular byte quickly among the more than 100,000 bytes stored on 


а — 


each dis diskette, Apple DOS divides a diskette into 35 tracks,-numbered.O fo 34. 
“Tracks are similar to. WIN REF PREE SE SRE see шөлі, ара 


“shown in 1 Figure 5- o 


Sectors 


_To о further speed up the search for a particular byte, DOS divides each track into 


716 sectors, as Figure 5-6 stows. Each sector holds exactly 256 bytes. Armed 
with. the t track and sector of a а particular byte, , DOS h has only 256 bytes to search. 


Now accessing а particular byte, or or series of bytes, is. almost. instantaneous Ihe 
real power of the disk drive is utilized. 


—— $— a a 
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Edge of diskette 
Center of diskette 


One track on the 
diskette surface 


FIGURE 5-5. Diskette Tracks 


256 bytes of data stored on one sector 


FIGURE 5-6. A Diskette's Recorded Surface 
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LOCATING TRACKS AND SECTORS 


Finding a track on a diskette is simple: the drive moves the head to the point on 
the diskette where the desired track is located, just as you would go about select- 
ing a particular song on a record album. 

Finding a sector is a little more difficult. There are two common methods used 
to locate specific sectors on diskettes. Both methods utilize a hole, called an /ndex 
hole, which is punched in the diskette envelope. On most diskettes the index hole 
is located near the large hole in the center of the envelope. As the diskette spins, a 
hole (or holes) located on the diskette itself passes the hole in the envelope. A 
light source inside the drive passes through to a sensor whenever the holes are 
aligned. The computer senses pulses of light and computes sector locations 
based on this information. 

There are two methods used to locate diskette sectors, called hard sectoring 
and soft sectoring. 


Hard Sectors 


Hard sectored diskettes have several holes, as shown in Figure 5-7. Each hole 
indicates the location of a sector. An extra hole marks the location of the first sec- 
tor. The computer locates sectors by counting holes following the first sector. 


Soft Sectors 


Soft sectored diskettes have just one index hole, as Figure 5-8 shows. It marks 
the first sector. Locations of other sectors are computed by timing the floppy 
disk's rotation. 

The Apple Disk ll uses soft sectored or hard sectored diskettes. The extra holes 
in hard sectored diskettes are ignored by the Disk Il. 


FIGURE 5-7. Hard Sectored Diskette 
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FIGURE 5-8. Soft Sectored Diskette 


WRITE PROTECTING 
M ÍÀ 


There is also a notch on the side of the envelope. This notch is used to enable or 
prevent information being written on the diskette. On 8-inch diskettes this notch 
is a write protect notch, because the computer will not write on a diskette if it has 
a notch on the diskette cover. On 5-1/4-inch diskettes the notch is called the 
write en i i i he 

i me di “System Master Diskette" supplied 
with the Disk Il, are protected permanently. They do not have a-notch. Notched 5- 


1/4-inch diskettes may be protected by covering the notch with a piece of tape. 
Figure 5-9 shows how this works. 


FIGURE 5-9. Write Protecting a 5-1/4-inch Diskette 
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THE DISK OPERATING SYSTEM 


All disk-related operations are controlled by a special program called the Disk 
Operating System, or DOS. BASIC transmits requests to DOS for any operation 
involving the disk. The DOS returns the results to BASIC. 


VERSIONS OF DOS 


Several versions of DOS now exist. DOS 3.3 is the most recent; this chapter de- 
scribes it. The chief difference between DOS 3.3 and DOS 3.2.1, the next most 
recent version, is the number of sectors they establish on a disk. DOS 3.2.1 has 
13 sectors, while DOS 3.3 has 16. Apple Computer Inc. has a special program 
which converts disks from DOS 3.2.1 to DOS 3.3. 


INITIALIZING DISKS 


Before Apple ІІ can use a diskette, the diskette must be /nitia/ized. Initializing a 
diskette erases all files from the diskette and places a copy of DOS in tracks O, 1, 
and 2. Disk Il initialization instructions are given later. 


DISK FILES 


Information is stored on diskettes as fi/es. A file can have any length that can be 
physically accommodated by the diskette. Every file has a name. A file may hold 
information like text, a computer program, or an image of an Apple ll graphics dis- 
play. The various types of files are discussed in more detail later. 


DISKETTE DIRECTORY 


D o0EnR pnm Re 

The name of every file on a diskette is stored in the diskette's directory. The direc- 
tory is located in track 17 of the diskette. The first entry in the directory is in sec- 
tor 15. The last entry is in sector 1. The directory has enough room to index up to 
84 files. 

Stored with each file's name is a code indicating the type of data in the file, the 

number of sectors it occupies, and the location of the sector that contains the 
file's track/sector list. 


TRACK/SECTOR LIST 


The track/sector list contains pairs of bytes which specify the track and sector 
address of each sector used by the file. Each pair of bytes is called a //nk. The first 
link in a track/sector list gives the address of the next sector used by the list itself. 
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The list may occupy as many sectors as it needs. The second link is the address of 
the first sector used by the file itself, the third link addresses the next sector used 
by the file, and so on. A link of zero marks the end of the list. 


Overview of the Disk Storage Process 


DOS controls the flow of all data to and from a diskette. When you write to a file, 
several things happen: 


1. DOS searches the diskette directory for the name of the file. (Your 
program names the file in order to identify it, as we will describe later.) 

2. If the name is found, DOS reads 256 bytes from the proper sector and 
stores them іп an area of memory called a buffer. |f the name is not 
found, or if that sector of the file has never been written to before, 
DOS fills the buffer with zeros. 

3. Up to 256 bytes of the data being written to the file are copied from 
memory into the buffer. If less than 256 bytes of data are copied into 
the buffer, prior data remains. 

4. |f, and only if, 256 bytes are written to the buffer, buffer contents are 
written back to the proper diskette sector. 

5. This process (steps 3 and 4) repeats until all of the data being written 
to the file has been copied into the buffer and stored on the diskette. 

6. After all the data has been written to the diskette, DOS updates the 
track/sector list and the directory. 


Note that unless the number of bytes you write to the file is evenly divisable by 
256, the last block of bytes will not fill the buffer, and steps 4 through 6 will never 
happen. Therefore а Disk Il command called the CLOSE command forces data in 
the buffer to be written to the file, after which the track/sector list and directory 


are updated. This process is called c/osing the file. Failure to close a file after writ- 


Җ ing to it can result іп loss of data. Always close а file when you have finished with 
b OR M1 P — ÜÓ—Ó————— 


it. The CLOSE command is discussed in more detail later. 
ia = 


DISK CRASH 


One of the worst disk errors that may occur is called a disk crash. There are two 
types of disk crashes: hard crashes and soft crashes. 

A hard crash occurs when the surface of the diskette is damaged, or has a 
physical defect, like a rip or a piece of dirt. A hard crash can cause damage to the 
read/write head inside the disk drive. The damaged head can, in turn, damage 
more disks. For this reason, always handle disks with care. 

A soft crash results when the directory track is overwritten with incorrect data. 

his most frequently occurs when one or more files have been written to but not 
closed, a different disk is placed in the drive, then the files from the original disk- 
ette are closed. To fully appreciate the resulting mess you must experience it. 
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BOOTING THE DISK II 


For the Apple Il to recognize any disk command, the special Disk Operating 
System program (DOS) must be in memory. If you had a lot of time on your hands, 
you could type DOS into memory via the keyboard. But there is an easier way: it is 
called booting the disk. Booting the disk, or booting DOS, reads a copy of DOS 
from a disk and places it in memory. 


HOW TO BOOT DOS 


There are several different ways to boot DOS, depending on the configuration of 
your computer and the language you use to initiate the boot. Each method 
assumes that the disk drive is connected to the DRIVE 1 pins on the disk controller 
card in slot 6. 

Insert the “System Master Diskette” into the drive and close the drive door. 
What you do next depends on the Apple system you are using. At the end of a 
successful boot, the display screen will look like one of those in Figure 
2-5. 


Autostarting 


Autostarting is the easiest way to boot DOS. As the name implies, booting is auto- 
matic. But to autostart, your computer must have the Autostart Monitor. You can 
tell if you have the Autostart Monitor installed by turning on the computer while 
the Disk Il is connected. If the red IN USE lamp on the Disk Il cabinet lights and the 
drive makes whirring and clicking noises, your Apple ІІ has the Autostart Monitor. 

To boot with an Autostart Monitor, simply turn on the Apple Il power switch. 


Booting from the Monitor 


When the Monitor prompt character (ж) appears оп the screen, the Apple Il As- 
sembly Language Monitor is waiting to accept commands. There are several 
different ways of booting DOS from the Monitor. 


Monitor Jump Booting 


Type the letter C, followed by the slot number of the drive you wish to boot (6 is 
standard), then two zeros and the letter G. The entire jump boot command should 
look like this: #06006 

C600 is the memory address of the program which boots from the drive in slot 
+6. G is the command that transfers control to that program. Now press Return. 
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The lamp on the drive should light and the drive will make whirring and clicking 
noises. 


Crat-K and Crn.-P Monitor Boots 


The other Monitor commands you can use to boot the DOS are Ста!-К and Стя. - 
P. To boot from the Monitor using either of these two commands, type the slot 
number (normally 6), then type Стнк-К or CrR.-P. The CrnL.-K or Crat-P will not be 
displayed on the screen. 

After typing the command, press the Retuan key. 


Booting from Integer BASIC 
or Applesoft 


The same boot commands are recognized by both Integer BASIC and Applesoft. 


Booting From BASIC 
Using the PR+ and IN+ Commands 


After the BASIC prompt character (> in Integer BASIC, ог | in Applesoft), type the 
letters PR or IN, then a pound sign (+), and finally the slot number of the disk you 
want to boot. The command should look like one of these: 

РКФФ 


or 
INS6 


Now press the Return key. 


Booting with the Apple Language System 


If you have the Language System installed in your Apple tl, the booting procedures 
above may not apply. It takes two disks to boot DOS versions 3.2.1, 3.2, and 
lower. But DOS 3.3 does boot as described above. 

To boot DOS 3.2.1, 3.2, and lower using the Language System, insert the disk- 
ette labeled "BASICS: Integer and Applesoft Il" (supplied with the Language 
System) in place of the "System Master Diskette” described above, then proceed 
with any boot procedure described above (autostart, PR#6, etc.). After a success- 
ful boot, the screen will display: 


INSERT BASIC DISK AND PRESS RETURN 


This is quite misleading. Actually you must insert a DOS diskette (the "System 
Master Diskette” will do, or you can use any diskette that has been initialized). 
After you have inserted the second diskette and pressed Return, booting will pro- 
ceed normally and you will see one of the displays shown in Figure 2-5. 
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BEGINNING DISK COMMANDS 


The Apple ІІ Disk Operating System interprets and executes disk commands. 
Many commands allow or require additional parameters that further define the 
operation to be executed. A few elementary commands are described below. 


CATALOG 


The CATALOG command outputs all the file names in the diskette directory to the 
current output device, usually the screen. 

The catalog first shows the diskette volume number. (Volume numbers are dis- 
cussed later.) 

For each file on the disk, CATALOG lists the type of data in the file, whether or 
not the file is /ocked, the number of sectors the file occupies, and the file name. A 
typical catalog is shown in Figure 5-10. 


File Types 


The type of data in a file is represented by the single-letter code which appears in 
the leftmost column of the catalog. The codes used are listed in Table 5-1. 


Locked Files 
ө------------е 
Locked files may not Бе written to or deleted. The catalog indicates that a file is 
locked by preceding the type code with an asterisk (*). If a space appears instead 
of an asterisk, the tile is not locked. Locked files are discussed later in this chapter. 
—— a — M ———— L 


OOo? HELL. 

[ 053 APPLE-TREK 

| O18 ANIMALS 
OO? UPDATE 3.2.1 
014 COFY 
Oo? COLOR DEMO 
об BRICK OUT 


O26 SPACE WAR 
| O50 THE INFINITE NO. OF MONKEYS 
O51 COLOR SKETCH 
Of2 SUPERMATH 
оре APPLEVISION 
O17 BIORHYTHM 
027 PINBALL 


FIGURE 5-10. Typical Disk Catalog 


Ҹ 
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TABLE 5-1. Disk File Type Codes 


LINKEN NN 


Applesoft programs 
Binary image files 


Integer BASIC programs 
Text files 


Number of Sectors 


The number of sectors the file occupies is shown as a three-digit number. The 
smallest (empty) files are one sector long. If a file has more than 255 sectors, this 
number is reset to O and starts over. This does not affect the true size of the file. 


File Names 


Apple ІІ DOS requires that you refer to a file by its name. Неге are the rules which 
govern the names you mm to files: 


1. File names must be from 1 to 30 characters in length. Excess 
characters are ignored. 
2. File names must begin with a letter. 
3. Any character you can type on the keyboard may be part of a file 
name, except commas. 
You may use nonprinting characters (like those created with the Стаі key) as part 
of a file name, but they will not show up in the catalog lis ing. is is useful if you 
want to prevent others from knowing your file names. (But do not forget whic 


nonprinting characters you used.) — — 


Using the CATALOG Command 


To use the CATALOG command, simply type it in (assuming DOS has been 
booted) like this: 
CATALOG 


The result should look something like Figure 5-10. 

If the number of lines in the CATALOG printout exceeds 20, the computer will 
display the first 21 lines and wait until you press any key on the keyboard (except 
Reset, Стві, and Surrr); then it displays the next 21. This pause gives you time to 
read all the file names before they scroll off the top of the screen. 
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LOAD 


The LOAD command reads a program file from the diskette into memory. You 
must specify the name of the file to be loaded. This example loads the program 
named COLOR DEMOSOFT: 


LOAD COLOR DEMOSOFT 


If the file name you specify is not in the diskette directory, you will get the error 
message FILE NOT FOUND. 

If the file is on the diskette, DOS checks the type of data in the file. If it is not a 
program file, you will get the error FILE TYPE MISMATCH. 

Assuming everything is OK, LOAD erases the program currently in read/write 
memory, then copies the program from the file into read/write memory. After the 
prompt and cursor return you may list, modify, or run the newly loaded program. 


THE DISK VERSION 
OF THE RUN COMMAND 


Frequently after you issue the LOAD command, you immediately issue the RUN 
command. You can abbreviate this two-step process by specifying a file name 
with the RUN command. The LOAD command becomes an implicit step, since the 
file must be loaded before it can be run. Here are a few examples: 


RUN PROGRAM 2 
RUN ЗЕСТ RUN 
RUN COLOR DEMOSOFT 


SPECIFYING THE DRIVE NUMBER 


Many DOS commands allow a disk drive to be specified. Two parameters specify 
a diskette drive: the drive parameter and the s/ot parameter. 

| an be connected to one disk ct a drive, 
add a comma and D1 or D2 to a diskette command as follows: 


LOAD UP,D2 
RUN AROUND, D1 
CATALOG, D2 


After you have used a drive specification once, subsequent disk commands will 
default to that same drive until you specify the other drive. The default drive is 
always the drive specified by the most recent command. If none has yet been 
specified, drive 1 is used. 


SLOT SPECIFICATION 


The Disk Il controller cards plug into slots inside the Apple ІІ. There are eight slots 
available, but slot number О cannot be used for Disk Il controllers? That leaves а 
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maximum of seven slots for Disk ІІ controllers. Since each controller will support 
опе or two disk drives, a maximum of 14 drives may be connected to an Apple 11. 

If you have more than two Disk Il drives connected to your Apple Il, you cannot 
refer to them as D3 or D4, etc. Instead, you must use another parameter to select 
the proper controller card. The parameter is called s/ot and is used to indicate 
which slot the disk controller you want to reference is plugged into. 

To use the slot parameter, you add a comma, the letter S, and the slot number 
(1-7) to disk commands, like this: 

CATALOG, SS 
LOAD TRUCKS, S4 
RUN OVER, S3 

The slot used when booting DOS becomes the default slot. This slot will be 
selected until another slot is selected by a slot parameter. 

After you have used a slot parameter once, subsequent disk commands will 
default to that same slot until you specify another slot. 

You may use both the drive and the slot parameters together, in the same com- 
mand. By specifing a slot number from 1 to 7, and a drive number of 1 or 2, you 
can refer to any Disk Il connected to your computer. The slot and drive parameters 
can appear in any order. The following two commands are equivalent: 

CATALOG, 02, 59 

CATALOG, 55, 02 
Both commands will produce the catalog of the diskette in drive number 2 of the 
controller in slot number 5. 


Y Problems with the Slot Parameter 


If you select a slot which does not have a controller in it, the computer will lock up. 


The computer is waiting for the nonexistent controller to signal it is ready. In order 
to recover with your program intact, press Reser. If you get a BASIC prompt (> ог 
everything should be OK. If you get the Monitor prompt (*), type 3D0G and 


press Return. If that doesn't work, you will lose your program be ou will 
have to reboot DOS. 


VOLUME SPECIFICATION 
ол ның 


Volume, is another parameter you may specify with every DOS command that 
allows the slot and drive specifications, except CATALOG. Volume allows you to 
make sure the correct diskette is in the drive you have selected. 

The CATALOG command ignores volume references. When the CATALOG 
command lists the diskette directory, the volume number of the disk is the first 
item listed. 

To use the volume parameter, add a comma and the letter V followed by a 
volume number, as follows: 

LOAD ZüNE;V1*?v1 
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If the volume number you specify is not the same as the volume number 
assigned to the diskette when it was initialized, DOS returns the error message 
VOLUME MISMATCH. 

Volume numbers must be in the range 1 to 254. If you do not specify a volume 
number, or if you specify a volume number of O, the volume parameter is ignored. 

You may use the volume parameter in conjunction with either the slot or drive 
parameter, or both, in any sequence. Here are some examples: 


LOAD CARGO, D2,V24 
RUN PAYROLL, 546.V111 


MORE DISK Il COMMANDS 


You now know how to see what is on a disk using CATALOG, and how to load 
and run programs. You are ready to put your own programs on disks, using the 
commands INIT, SAVE, DELETE, LOCK, RENAME, and VERIFY, which are de- 
scribed below. 


INIT 


Before you can write on a diskette, remember that it must first be initialized. 
When a diskette is initialized, anything stored on it is erased, so make sure you do 
not initialize a diskette containing data you want to save. 

The INIT command stores on the diskette any program that is in memory when 
you use the INIT command. This becomes the greeting program, which is auto- 
matically run every time you boot from that diskette. The greeting program can be 
as simple or as complex as you desire. For example, suppose you have a diskette 
that contains a mailing list. You could use the mailing list program as the greeting 
program. Then when you put the diskette in the drive and boot, presto! The mail- 
ing list program is up and running. Another example is a greeting program that 
consists of a NEW statement and an END statement. Every time the disk is 
booted, you will get the BASIC prompt (> or 1). 

A well written greeting program should tell you something about the diskette. 
A typical greeting program might look like this: 


100 TEXT 

200 CALL - 926 

300 PRINT "THIS IS MY FIRST DISEETTE." 
400  FRINT 

SOO PRINT “INITIALIZED 2/14/31" 

400 PRINT 

700 PRINT “ON А 48K SYSTEM USING DOS 3.3" 
200 END 


The file name of the greeting program must be specified when you use the INIT 
command. It is your responsibility to make sure there is always a program by that 
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name on the diskette. If you delete the greeting program (we'll describe how 
later), you will see the error message FILE NOT FOUND every time you boot from 
that diskette. The only way to stop that error message is to put a program on the 
diskette with the greeting program's file name. That might be difficult to do if you 
do not know, or cannot remember what file name was assigned, because there is 
no way of determining what the name of the greeting program is. The best solu- 
tion is prevention. A/ways specify the same greeting program file name when you 
initialize diskettes. The standard greeting program name is HELLO. 


Using the INIT Command 


A typical INIT command looks like this: 
INIT HELLO; S6;I1;WV36 


As you might suspect, the slot, drive, and volume specifications are optional. If 
you include the volume parameter, DOS assigns the specified volume number to 
the diskette. INIT is the only command that assigns the volume number. When the 
volume parameter is used with other DOS commands, the number specified must 
match the number assigned by INIT. If you omit the volume parameter, INIT will 
assign a volume number of 254. 

As always, omitting the slot or drive parameters will cause them to default to 
the values specified by the previous DOS command. Be sure you know which 
drive the INIT command is going to select. If you are not positive, specify! 

To initialize a new diskette, first remove the “System Master Diskette” from 
the drive and replace it with a new, blank diskette. Use the NEW command to 
make way in memory for the greeting program. Then type in the greeting program 
shown above, or a greeting program of your own. It is a good idea to test run the 
greeting program before it is stored on the diskette. 

Let's assign a volume number of 123. Now type: 


INIT HELLO; 56. D1,V123 
Make sure the drive door is shut, and press Return. The red lamp on the drive 
should light, accompanied by the usual whirring and clicking sounds. The entire 
process takes about two minutes, so be patient. After the lamp goes out, use the 
CATALOG command to see what is on the new disk. The result should look like 
this: 
LISK VOLUME 123 
I 002 HELLO 
or, if you are using Applesoft, you should see: 
DISK VOLUME 123 
A 002 HELLO 


The letter | means the greeting program was written in Integer BASIC. The let- 
ter A means it was written in Applesoft. The 002 means the program is two sec- 
tors long. You might see a different number, depending on the length of your 
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greeting program. 

Prepare a label for your diskette. You should write the volume number on the 
label, along with any information you may want to know about this particular disk- 
ette. Remove the diskette from the drive, apply the label, and replace the diskette 
in the drive. If you want to reboot using the diskette you have just prepared, you 
can do so now. 


SAVE 


If you have kept up with the hands-on part of this chapter, you will now have a 
freshly initialized diskette in drive 1, slot 6 of your Apple Il. You probably also have 
a copy of your greeting program in memory. Use the LIST command and see if it is 
there. If it is not, type: 

LOAD HELLO 


to get a new copy from the disk. 

The SAVE command stores programs on a diskette. To save another copy of 
your greeting program, type the SAVE command followed by a file name. For this 
example, we will use the file name GREETING PROGRAM. You may use any valid 


file name you wish. 
SAVE GREETING PROGRAM 


The disk should spin and make its usual racket. When SAVE is finished, the 
BASIC prompt and cursor will reappear. Next, use the CATALOG command to 
check the disk contents. What you see should look something like this: 


DISK VOLUME 123 


A 002 HELLO 
A 002 GREETING PROGRAM 


You can save any BASIC program you desire this way. 

If you use a file name that is already on the diskette, whatever program you are 
saving will replace the program with the same name that was stored on thé disk- 
ette. Thus the old program is automatically erased. This works as long as the old 
program and the new program are in the same version of BASIC. If they're not, the 
new program will not be saved. Instead, the message FILE TYPE MISMATCH 
appears. 


DELETE 


After a while, you will probably accumulate many programs on a diskette which 
no longer serve any useful purpose. The DELETE command removes files from the 
diskette. 

To delete the copy of the greeting program you just saved, any of the following 
commands will do the job (unless you have referenced a different disk drive since 
then). 
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DELETE GREETING PROGRAM, 56, р1>У12 
DELETE GREETING FROüGRAM;V123 
DELETE GREETING PROGRAM 


Remember that you can use the slot, drive, and volume parameters in any order 
you wish, or not at all if the default drive is the one you want to access. 


LOCK 


Some program or data files on a diskette must be kept permanently. For this pur- 
pose, DOS supports a protective technique called file /ocking. Locking a file pre- 
vents it from being accidentally deleted or written over. To lock a file, enter the 
LOCK command, followed by the file name and the optional drive, slot, and 
volume parameters. The following command locks the greeting program: 

LOCK HELLO 
It is a good idea to LOCK the greeting program. 

Subsequent attempts to delete or write to locked files will result in the error 
message FILE LOCKED. 

If the locked file is an Integer BASIC or Applesoft program and you try to save a 
program that has the same name but is written in the other BASIC, then you will 
get the error FILE TYPE MISMATCH. 

On a diskette catalog, locked files are indicated by an asterisk (*) preceding the 
file type. 


UNLOCK 


When you decide to write over or delete a locked file, you can remove the lock 
with the command UNLOCK. The following statement unlocks the greeting pro- 


gram: 
UNLOCK HELLO 


As always, slot, drive, and volume specifications are optional and can occur in 
any order. 


RENAME 


You can change the name of any file on a diskette. One way to change the name 
of a program file would be to load it, delete it, then save it with the new name. A 
better way is to use the RENAME command. RENAME works for any file on the 
disk, regardless of which BASIC you are using. RENAME also works for text files 
and binary files. Here is an example of RENAME: 


RENAME CILONAME, NEWNAME 
DOS will not check to see if the new file name is already on the diskette. If it is, 
you will end up with two files that have the same name. This can be very confus- 
ing and difficult to recover from. 
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Do not RENAME the greeting program unless you put a new program with the 
old name on the diskette. RENAME does not change the name DOS looks for 
when the diskette is booted. 

You cannot change the name of a file which is locked. 

You may specify slot, drive, and volume numbers (in any order) if you wish. 


VERIFY 


Occasionally, you may want to check that a file is intact. The best way to do this is 
using the VERIFY command. The following command will check out the greeting 


program: 
VERIFY HELL.O,V12:3 


As DOS writes out each sector of a file, it computes a number, referred to as a 
checksum. The checksum value is based on the numeric value of each character 
in the sector. The checksum is stored with the sector. When you issue the VERIFY 
command, DOS recalculates the checksum for each sector of the file and com- 
pares the computed checksums with the stored checksums. If there is any 
difference between the values, DOS returns the error message 1/0 ERROR. 

If all the computed values match the stored values, DOS does not return any 
message; the BASIC prompt and cursor simply reappear. 

As with most other DOS commands, you may specify slot, drive, and volume 
numbers in any order if you wish. 


USING DOS COMMANDS 
IN PROGRAMS 


Until now all DOS commands have been typed in on the Apple ІІ keyboard. But 
BASIC programs that use files can include DOS commands. 


To use a DOS command from within a BASIC program, you put it in a PRINT 


statement, prefixed with ап ASCII code 4 character. Use CrnL-D to create this 

prefix. C-D must be the first character output by the PRINT statement. Be зше, 

that the previous PRINT statement did not terminate with a semicolon or a 

7.7 наа волы ы; айран 
Since Crn.-D produces а nonprinting character, it is recommended that you 

document each occurrence with a REM statement, like this: чин 
ы е с а Са Сысы сше тыа ы 


1000 PRINT "RUN MENU" : REM THERE IS А CTRL-D 
BETWEEN THE FIRST QUOTE ANI THE R IN RUN 


You can simplify things by defining a variable as CrnL-D, then printing the 
variable followed by the DOS command. The variable D$ is commonly used for 


this, but you can use any name you wish. Using the standard variable D$ in all 
MM ————————————— 
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your programs makes them compatible with each other, and with everyone else's. 
Add a line like this to your BASIC programs: 
10 ПФ = "": REM THERE IS AN INVISIBLE 
CTRL-[ BETWEEN THE GUOQTES 


or, in Applesoft, you may use: 
* 10 m$ = CHRS (4): КЕМ ІІНК%(4) = CTRL-I! 
Then wherever D$ is used, it is easy to see that it is a CrRL-D character. 
Try running the program shown below on your Apple Il: 
10 D$ = "": REM CTRL-D 
20 FOR I = 1 TO 10 
ЗО PRINT Ds "CATALOG" 


40 NEXT I 
20 END 


displayed 10 times, without touching a key. If there are more than 18 catalog 


T you have more than 18 files on the diskette, you should see the catalog 
entries, you'll have to press a key each time a pause occurs. 


USING DISK FILES 


Apple DOS supports two types of disk files: seguentia/ files and random-access 


files. Both types of files contain blocks of data, called fields. A field may be one 
character or many characters long. 


Sequential Files 


Sequential files, as the name implies, can be accessed in a sequential manner only. 
To read or write the last field in the file, you must first read or write all previous 
fields. For some applications, sequential access is fine. 


Random-Access Files 


Random-access files allow more flexibility than sequential files do. You can read 
or write any field in the file without regard to its location. For many applications, 
random-access files are the best solution. 


USING SEQUENTIAL FILES 
к= end ieee 


In order to use sequential files, you will need to learn a few more DOS commands: 
OPEN, CLOSE, READ, and WRITE. 
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Disk files must be opened before they can be accessed. Opening a disk file causes 

DOS to retrieve information about the file: whether it is on the disk, and if so, 

where it is on the disk. OPEN also sets aside an area of memory to be used as a 

buffer for the file. The buffer allows you to access a small portion of the file with- 

out activating the disk drive on every field access, and that saves a lot of time. The 
EN command looks like this: 


СРЕМ FILENAME, 54, 02, VFP 


If the file does not exist as specified, DOS will create a new file entry іп the disk 
ВА 
"Within a program the OPEN command must be in a PRINT statement and be 
SEE s oec Sr 


The program below will do nothing more than create the sequential file 
UENTIAL on the disk in the default drive: 


100 D$ = "": REM CTRL-D 
200 PRINT D$:"OPEN SEQUENTIAL" 
300 END 


4—- We will call this Program 7. 
You can include any combination of slot, drive, and volume parameters with 
the OPEN command: 


100 ПФ = "": КЕМ CTRL-D 
200 PRINT ПФ%"ПРЕМ SEGLIENTIAL;' S5,D1.V1z3" 
200 ЕМГ 


or: 
200 FRINT [$3 "СРЕМ SEGUENTIAL, V123,54 


Note that all the parameters occur before the closing quotes, and that they are 
separated by commas. 


+- After you run the program, the file SEQUENTIAL will be in the catalog. Confirm 
this by typing CATALOG. The catalog should look something like this: 


DISK VOLUME 123 
#A 002 HELLO 
T 001 SEQUENTIAL 


Ж- Note the letter T before the number of sectors in SEQUENTIAL. T is the code 
which designates SEQUENTIAL as a text file, as opposed to an Applesoft or 
Integer BASIC program file, or a binary file. The asterisk (*) preceding the type of 
file HELLO indicates it has been locked. 


Closing Files 
eS ee 


Actually, Program 1 is a very poor program, for one big reason: it does not close 
the file when it is finished. The CLOSE command is very important. Not closing 


files can result in loss of data, and possible destruction of r diskette 
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(see the section on soft crashes in this chapter). The CLOSE command has two 
formats. The first one is: — 
pum ln nad 
CLOSE 
The CLOSE command with no parameters will close all open files, on all diskettes, 


regardless of УСТ drive 5107; or volume they reside on — —— — — 7 
ometimes you may want to close one or more specific files. You close 
individual files by adding the file name to the CLOSE command, like this: 
n AA———————————— ——————————————)"J——:—— 


CLOSE FILENAME 
No slot, drive, or volume parameters are allowed or required with either form of 
the CLOSE command. DOS knows where the file is, since the file is already open. 
Program 1 should be corrected by adding this line: 


290 PRINT Ds "CLOSE" 
or, you could add: 
270 PRINT ПФ; "CLOSE SEQUENTIAL" 


Writing to Sequential Files 


Program 1 is a pretty useless program. Diskettes are used to store and retrieve 
information. Since you cannot retrieve anything that isn’t already on the disk, we 
will discuss how to store information first. 

Information is sent to the Disk Il the same way it is sent to the screen or printer: 
via the PRINT statement.*Anything you can print can be put in a disk file. In fact, 
you might visualize a sequential file as a TV screen, or even better, as paper in a 
a ир ЬЕ ЕУ А 

When you print something оп а file, DOS updates an internal pointer which 
points to the next location on the disk surface where data will be stored, just as a 
printer advances paper to the next line. 

A sequential file pointer can only be moved forward. The OPEN command 
moves the pointer back to the beginning of the file. 

Before you can print data to a disk file, you must first use a WRITE command to 
tell DOS that PRINT statements are To write to a Tile instead of the display screen. 
For sequential files, the WRITE command looks like this: 


WRITE FILENAME 


After you issue the WRITE command, subsequent output will be directed to the 
specified file. Note that subsequent output will include any error messages. 
However, after the error message is stored on the file, the WRITE command is 
cancelled. You will see only the BASIC prompt and cursor on the display screen. 

The WRITE command must be in a PRINT statement, preceded by a CrRL-D 
character. If you issue the WRITE command in immediate mode you will get the 
error NOT DIRECT COMMAND. 
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Add the following lines to Program 1: 


210 PRINT Dts "WRITE SEQUENTIAL" 
220 PRINT "THIS TEXT WILL RE STORED IN THE. FILE" 


The program does the following: 


1. It creates a file, if it needs to. 
2. It opens the file. 

3. It stores text in the file. 

4. It closes the file. 


You may insert as many PRINT statements between lines 210 and 290 as you 
wish. You may print text, numbers, and variables, in any combination, as long as 
the syntax for the PRINT statement is correct. For example: 


220 FOR I = 1 TO 100 

230 PRINT I 

240 NEXT I 

250 PRINT “ABCDEFGHI JIKLMNOFORSTLIVWXYZ" 


Note that you only use the CrRL-D character prefix with DOS commands, never 
when writing the contents of a file. 

Be careful not to print characters to a file while FLASH or INVERSE statements 
are in effect, as these characters are not properly handled by DOS. 

Remember that each time you run this program, whatever is in the PRINT 
statements will overwrite and erase data already stored on the file. If you PRINT 
fewer characters than are already in the file, the tail end of the previous data will 
remain, following the new data. 

One way to circumvent the problem of leftover data is to erase the file before 
you store new data in it. The DELETE command (in the usual PRINT statement 
context) may be incorporated into the program just prior to the OPEN command. 
Every time the program is run the file will be deleted and then recreated by the 
OPEN command. 

However, a problem will then occur if you try to run the program when there is 
no file called SEQUENTIAL on the diskette. If you do, you will see the error FILE 
NOT FOUND. You can prevent that by adding another OPEN command, just prior 
to the DELETE command. This is what happens: 


1. The first OPEN command creates a file if one does not already exist. 
2. The DELETE command erases the file, no matter when it was created. 
3. The second OPEN command creates a new, empty file. 
As you make these changes to Program 1, remember that once you have 
specified the slot, drive, and volume, you don’t need to specify them again, unless 
you wish to refer to a different disk drive. With this in mind, use an OPEN com- 


mand with the slot, drive, and volume parameters as the first DOS command, and 
allow subsequent commands to default to those values. 
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If you have made these changes to Program 1, your listing should now look like 


this: 
100 D$ = "": REM CTRL-D 
110 PRINT 0%; "ОРЕМ SEQUENTIAL;V123,26,D1" 
120 PRINT OS: "DELETE SEQUENTIAL" 
200 PRINT 0%; "ОРЕМ SEQUENTIAL" 
210 PRINT D$3 "WRITE SEQUENTIAL" 
220 PRINT "THIS TEXT WILL BE STORED IN THE FILE" 


290 РКІМТ D$:"CLOSE" 
300 END 


Whenever you run this program, it will store the contents of the PRINT state- 
ments between lines 210 and 290 in the file SEQUENTIAL. You can use any file 
name you wish, but if you change a file name, be sure to also change every 
reference to the changed file name. 

You can use a variable for the file name and have the program ask for the name 
of the file to access. With this modification, the program looks like this: 


10 INPUT "FILE NAME: "РФ 
100 D$ = "": REM  CTRL-D 
110 PRINT 0%: "OPEN "5 ЕФ: ", 1213,54, 01" 
120 PRINT ПФ; "ПЕ ЕТЕ "sF$ 
200 PRINT [$3 "ОРЕМ FS" 
210 PRINT 0%; "WRITE ":F$ 
220 PRINT "THIS TEXT WILL BE STORED IN THE FILE" 
290 PRINT D$3 "CLOSE" 
ЗОО ЕМГ | 
You can go even further and have the program request the slot, drive, and 


volume numbers by making these changes: 


10 INPUT "FILE NAME: "sF$ 

20 INPUT "SLOT NUMBER: "35 

ЗО INPUT “DRIVE NUMBER: "50 

40 INPUT “VOLUME NUMBER: "3; 

100 ПФ = "": КЕМ CTRL-D 

110 PRINT OSs "ОРЕМ "sF$:;",S"s:;Ss:",D"sDs'",V"5 


When you make these changes, be sure to enter them exactly as shown. Do 
not forget to include the commas before the S, D, and V parameters, or DOS will 
not be able to distinguish the parameters from the file name. 

To make this program really useful, it should let you input the text to be stored, 
instead of having to change the PRINT statements. One way to do this is: 


150 INFUT "ENTER THE TEXT TO STORE: "3 ТФ 


220 FRINT T$ 
But that only allows you to enter and store one line of text. You could fix that by 
adding more INPUT statements, followed by more PRINT statements, but once 
again you have fixed the amount of text which can be entered and stored. Why 
not add a test after the INPUT statement so you can signal the end of your text? 
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Then add a GOTO after the PRINT so you can enter another line: 


150 INPUT "ENTER THE TEXT TQ STORE: ":T$ 
160 IF T$ = "END" THEN 290 

210 PRINT 0%; "ИКІТЕ ":F$ 

220 PRINT T$ 

230 dGüGTO 150 

Now whenever you are finished entering text, you can type END and the file will 
be closed. But there is still one big problem. Remember that the WRITE command 
causes all output to be directed to the file. Since the INPUT statement outputs the 
prompt ENTER THE TEXT TO STORE:, that line will not appear on the screen after 
the WRITE has been executed; it will be stored as part of the diskette file. 

The WRITE command must be cancelled in advance of output not intended for 
the diskette. Any DOS command will cancel the WRITE command, but the safest 
one to use is the nu// command, which is the CrRL-D character all by itself. Add 
this line to the program. 225 PRINT D$ 


With all these changes complete, you now have a program that will allow you 
to store any amount of text you wish (up to the maximum amount the diskette will 
hold), under any file name you choose, on any drive connected to your Apple Il. 


Reading Sequential Files 


Just as output can be directed to the disk, input can be accepted from a disk file. 
The READ command identifies a disk file as the source for data input. For sequen- 
tial files the READ command looks like this: 
READ FILENAME 

The READ command must be іп a PRINT statement, preceded by а Crn.-D 
character. If you issue the READ command in immediate mode you will get the 
error NOT DIRECT COMMAND. 

After the READ command has been executed, subsequent INPUT statements 
receive data from the specified file until another DOS command, or an error, can- 
cels the READ command. Program 2, below, demonstrates use of the READ com- 


mand. 100 D$ = "": REM CTRL-D 


110 INPUT "FILE NAME TG READ: "РФ 
120  INFLT "SLOT NUMBER: ":5 
130 INPUT "DRIVE NUMBER: "3П 
14а0 INPUT “VOLUME NUMBER: ":У 
150 PRINT 0%; "ПРЕМ “SF$5",5"353", D's Ds",V"$ 
140 PRINT Ds "READ "F$ 

170 INPUT AS 

120 РКІМТ A$ 

130 GÖTÜ 170 

200 END 


Program 2 will display all of the text in a disk file created by Program 1. After all 
of the file's contents have been output, you will see the message END OF DATA 
and the program will stop with the message BREAK IN 170. 
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You may notice that Program 2 lacks a CLOSE command. We have explained 
why files must be closed when they are no longer needed, but in this case the file 
is never written to, therefore the directory or track/sector information never needs 
to be updated (assuming the file name you specify actually exists). The file should 
be closed, just to be safe. 

It is not a good practice to write programs that print error messages and stop 
under circumstances as predictable as reaching the end of data in a file. 


Preventing the END OF DATA Error 


The END OF DATA condition can be detected before an error is generated. Pro- 
gram 2 could branch control to a CLOSE command upon detecting an end of data. 
The easiest way to detect an END OF DATA is by using the Applesoft ONERR 
GOTO statement (discussed in Chapter 4), but ONERR GOTO is not available in 
Integer BASIC. (DOS error codes are explained in Appendix C.) 

Another way to find the end of text in files written by Program 1 is to modify 
Program 1 so that when you type the word END all by itself, a special word or 
character is written to the file just before it is closed. Then change Program 2 to 
look for the special end of text marker and CLOSE the file properly. This method 
will work in both Integer BASIC and Applesoft. 


Integer BASIC and 
Applesoft Differences 


The READ command identifies a disk file as the data source for subsequent 
INPUT statements. But the INPUT statement syntax must conform to the BASIC 
in which the program is written (see Chapter 8). Nevertheless, data supplied by a 
file depends on how that data was stored. 

In Applesoft, for example: 


100 [I$ = "": КЕМ CTRL-D 
200 PRINT П%:"ОРЕМ FILE1" 
200  FRINT 01%; "WRITE FILE1" 


400 PRINT "HELLO","THIS IS A TEST" 
S00  FRINT ПФ; "CLOSE" 
600 END 


and the same program with this minor change: 
400 PRINT "HELLO, THIS IS А TEST" 


both store two lines of text on FILE1. Applesoft does not handle the comma as a 
separator the same way Integer BASIC does. If you try to read the text in FILE 1 
шш 400 PRINT D$:"READ FILE1" 

400 INPUT А% 
while in Applesoft, you will get the message ?EXTRA IGNORED and the variable 
A$ will be set to HELLO, regardless of which line 400 was used to store that text. 
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In Applesoft, commas separate multiple values in a single PRINT statement. 

Integer BASIC will accept both lines as one, so the value of A$ stored by the 
first example will be HELLO THIS IS A TEST, and the value of A$ from the second 
version of line 400 will be HELLO, THIS IS A TEST. 


Using the Applesoft GET 
Statement to Read Text Files 


In Applesoft the GET statement can be used to read data from a disk file. The GET 
statement differs from the INPUT statement in that the GET statement returns 
one character at a time. Thus, if a file contains the text THIS FILE CONTAINS 
TEXT, and you execute an OPEN, a READ, and then a GET, the first GET will return 
the letter T. The next GET will return H, and subsequent GET statements will 
return |, S, a blank space, F, |, L, E and so on, until every character of the text has 
been read. If the GET returns a comma or a carriage return, the program can 
detect it and interpret it properly. 

Program 3, shown below, demonstrates how a file may be read by using the 
Applesoft GET statement to build a line of text, one character at a time. 


100 D$ = CHR$ (4): REM CTRL-D 

200 INPUT "FILE NAME TO READ: "РФ 
300 INPUT "SLOT NUMBER: ":S 

400 INPUT "DRIVE NUMBER: "30 

S00 INPUT "VOLUME NUMBER: "$V 

500 PRINT П%: "OPEN "SFOS", V°S VS", 03 Ds", S" $3 
700 PRINT П%: "READ ":F$ 

800 BS = "" 

900 GET AS 

1000 IF A$ = CHR$ (13) THEN 1300 
1100 BS = BS + AS 

1200 GOTO 900 

1200 REM RETURN CHARACTER FOUND 
1400 REM BS IS COMPLETE 

1500 РКІМТ BS 

1500 GATI Зоо 

1700 ЕМІ 


But the GET statement has a problem when used with disk files. The first 
character printed after a GET has been executed is ignored. If the first character 
printed is а DOS command, then the CrnL-D character will be ignored, which 
means the entire command will be printed, not executed as a DOS command. 

The cure for this problem is to print a throw-away character first, one that is 
intended to be ignored. A good character to use is Стн1-А (ASCII code 1), since it 
is nonprinting and has no special meaning (as opposed to Crat-D, for example). 

Program 3 can be patched, or corrected, by changing line 1500 to read: 


1500 PRINT CHRS (1) 5 В%: REM CHRS(1) = CTRL-A 


Chapter 5: THE DISK II 185 


Storing Numbers in Files 


You may have used Program 1 to store numbers in a file, either as part of some 
text, as in: 
220 PRINT "MY ADDRESS IS 1224 NORTH STREET" 


or directly as numeric values: 

230 PRINT 1,2,3,4,5 
or via numeric variables: 

240 PRINT А.В.С.ПГ-Е 


If you stored numbers directly, you will get some strange results when you READ 
them back with Program 2. 

Using Integer BASIC, numbers separated by commas or semicolons will form 
one big number (12345 from line 230 above), for a total of one line of output. 

Using Applesoft, things become even more confusing. The first three numbers 
are concatenated (123) and printed as one line of output. The next two values (4 
and 5) produce one line of output each, for a total of three lines of output. 

These problems result from the format used to store information in disk files. 
Commas are not stored between the numbers if they would not be displayed on 
the screen. Instead, on the screen the commas cause the next value to appear at 
the next TAB position. When output is directed to a disk file, however, DOS dis- 
cards commas completely. Nothing equivalent to tabbing occurs. As a result, 
values become concatenated until a carriage return (ASCII code 13) separates 
them. The carriage return is the only character DOS interprets as a value sepa- 
rator. Integer BASIC outputs a carriage return after the fifth tab stop (comma), 
while Applesoft does it after three tab stops. 

To avoid problems, you should make sure that each numeric field you store in a 
disk file is followed by a carriage return character. The easiest way to do this is to 
output each number with a separate PRINT statement: 


220 PRINT 1: PRINT 2: PRINT 3: PRINT 4: 
PRINT 5 


Another method available to Applesoft users is to include a carriage return 
character as a separator in the PRINT statement parameter list: 


230 PRINT 13CHRS(13)3 23 CHR$(1325 33 CHRS(1 
3)3 45 CHRS(13)35 


You may prefer to define a variable as a carriage return character, then print the 


variable: 
11 R$ = CHR$(12): REM RETURN CHARACTER 


230 PRINT 1:R$;2:R$: 3:3R$: 43 КФ55 


This makes for a cleaner program. 
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HOW TO APPEND TO SEQUENTIAL FILES 


A sequential file should be closed when written into. When you CLOSE a file, you 
lose track of where the last item was stored. To add data to the end of the file, 
therefore, you must first find the end of the file. You could read each item in the 
file until you reach the last one, but that can be very time consuming with large 
files. The APPEND command does the work for you. 

The APPEND command places the file pointer at the first unused character 
beyond the end of the file. If you read after the APPEND command has been 
issued, you'll get an END OF DATA error. If you write after an APPEND, the new 
data will be added to the end of the data already on file. 

The APPEND command is used in place of the OPEN command. There are two 
important differences between the APPEND and OPEN commands: 


1. APPEND requires that the file already exist. If it does not, the error FILE 
NOT FOUND is returned. APPEND will not create a file; APPEND 
assumes the file exists. 


2. APPEND places the pointer at the end of the file. OPEN places the 
pointer at the beginning of the file. 


The format for the APPEND command is the same as for the OPEN command. 
Here is an example: 
APPEND FILENAME, 34, 02, V99 


As always, the slot, drive, and volume commands are optional. 


THE POSITION COMMAND 


Another useful command is the POSITION command. POSITION moves the 
pointer forward (never backward) by the specified number of fields relative to the 
current pointer position. POSITION looks like this: 

POSITION FILENAME, R30 


R indicates relative field; the number after R is the number of fields to skip. 
Fields are marked by carriage return characters, so the POSITION command 
above counts 30 carriage returns beyond the current position and moves the file 
pointer there. If you specify RO, the pointer is not moved. 

POSITION actually examines the file character-by-character, starting from the 
current position. If there are not enough fields, or if an unused byte is encoun- 
tered, the error END OF DATA is displayed immediately. Executing an INPUT or a 
GET is not necessary to cause the error. 

A file must be open before it can be referenced by a POSITION command. 
When you open а file, the pointer is set to the beginning of the file. If you issue a 
POSITION command when the pointer is at the beginning of the file, it will effec- 
tively select the absolute field within the file. 

Remember, just like any other DOS command, POSITION cancels both the 
READ and WRITE commands. Be sure to execute POSITION before issuing a 
READ or WRITE command, not after. 
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USING RANDOM-ACCESS FILES 


Random-access files are structured into sections called records. Each record in a 
particular file holds the same amount of information, which is defined as some 
number of bytes (characters) when the file is created. 

The amount of information which can be stored in one record is referred to as 
the record /ength. 

Records are identified by a number indicating their absolute position in the file. 
The first record in every file is record number O, the next is number 1, followed by 
record 2, and so on. 

The smallest random-access file has one record. Files expand as new records 
are added, but they do not shrink. To remove unwanted records from a random- 
access file and shrink the size of the file, you must copy the records which are to 
be preserved into a new random-access file. 

Programs must specify which record of a random-access file is selected, and 
what part of the record is to be accessed. 


Opening Random-Access Files 


To define a file as a random-access file, you must include an additional parameter 
when the file is opened: the /ength parameter. The length parameter (L) specifies 
the length of each record, like this: 


ОРЕМ FILENAME;L. 10,56; D1,;V100 


The length parameter must have a value ranging between 1 and 32767. It does 
not have to be the first parameter in the list, but it must be present if the file is to 
be random-access. 

Programs should never write records that are longer than the number of bytes 
specified by the length parameter. That includes carriage returns and commas. If 
too many characters are stored in a record, the succeeding record may be over- 
written or combined, creating a real mess. 


Closing Random-Access Files 


The CLOSE command is identical for both sequential and random-access files. 


Random-Access Read and Write 


The READ and WRITE commands require a record parameter for random-access 
files. The record parameter moves the file pointer to the beginning of a record. 
The following example uses the record parameter (R): 

READ FILENAME, Ris 

WRITE FILENAME,R4 

The record parameter need not be the only one in the list. You may also specify 

slot, drive, and volume. Parameters may appear in any order. If the record 
parameter is not present, the pointer is not moved. 
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A PRACTICAL RANDOM-ACCESS EXAMPLE 


The following programs demonstrate a practical use of random-access files. The 
programs will work in either Applesoft or Integer BASIC. In order to use the sec- 
ond program in Integer BASIC, you must add a DIM statement before line 100 for 
variables B$ and C$ (255 characters each).The first program creates a file called 
RANDOM. 


10 КЕМ RANDOM-ACCESS FILE CREATING PROGRAM 
20 КЕМ 
30 КЕМ BE SURE TO RUN THIS PROGRAM FIRST AS IT 


40 REM STORES INFORMATION IN RECORD ZERO WHICH MUST 

S0 REM EXIST FOR THE NEXT PROGRAM TO FUNCTION. 

60 REM 

100 ПФ-"" : REM CTRL-D 
200 PRINT 0%; "СРЕМ RANDOM, 66, 11,1256" : REM OPEN THE FILE 
ЗОО PRINT D$:"WRITE RANDOM,RO" : REM WRITE, RECORD ZERO 
400 PRINT © : REM STORE А ZERO IN RECORD ZERO 
500 PRINT D$;"CLOSE" : REM CLOSE THE FILE 
600 ЕМЕ 


Once the file has been created, the second program allows you to read, 
change, add, and list the records in the file. Each record will contain one line of 
information which you type in at the keyboard. 


10 REM RANDOM-ACCESS FILE DEMONSTRATION PROGRAM 
20 REM 

30 REM THIS PROGRAM WILL MAINTAIN А RANDOM-ACCESS 
40 REM FILE WHICH CONSISTS OF SINGLE LINE RECORDS. 
SO REM 

£0 REM RECORD ZERO CONTAINS A NUMBER INDICATING 
70 REM THE LAST RECORD NUMBER IN USE. 

во REM 

25 КЕМ NOTES FILE “RANDOM” MUST BE CREATED BEFORE 
90 REM ATTEMPTING TO USE THIS PROGRAM. 

95 REM 

100 D$="" : REM CTRL-D 


200 PRINT 0%; "ОРЕМ RANDOM;S6;D1,L256" 

229 PRINT 0%; "READ RANDOM.RO" = REM READ RECORD ZERO 
290 INPUT М: REM M = THE LAST RECORD NUMBER IN USE 
275 PRINT 0% : REM CANCEL READ СОММАМП 

300 CALL -936 : КЕМ CLEAR SCREEN 

400 PRINT "RANDOM-ACCESS FILE DEMONSTRATION" 

500 PRINT : PRINT = PRINT : PRINT 

600 PRINT "COMMANDS?" : PRINT 

700 PRINT " О STOP" 

S00 PRINT " 1 READ А RECORI!" 

900 PRINT " 2 ADD A RECORD" 

1000 PRINT "3 = CHANGE A RECORD" 

1100 PRINT "4 = LIST ALL RECORDS" 

1200 PRINT = PRINT 
1300 PRINT "WHICH"; 
1400 ІМРІТ С 

1500 IF CzO THEN &300 
1600 IF C-1 THEN 2200 
1700 IF C=2 THEN 3300 
1800 IF C23 THEN 4400 


REM BRANCH 
REM та 

КЕМ ТНЕ 

КЕМ SELECTED 
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1900 
2000 
2050 
2100 
2150 
2200 
2300 
2400 
2500 
2600 
2650 
2700 
2300 
2900 
3000 
3100 
3150 
2200 
3250 
3300 
3400 
39500 
3600 
3625 
3700 
3750 
3800 
3900 
4000 
4100 
ZERO 
4200 
4300 
4400 
4450 
4500 
4550 
4600 
4700 
4800 
4900 
5000 
50950 
5100 
5200 
5300 
5400 
S500 
5600 
5700 
5800 
5700 
6000 
6100 
200 
6300 


IF C=4 THEN 6700 REM ROUTINE 


GOTO 300 REM (DR RE-DISPLAY THE MENU) 
REM 

REM # s ss # oc READ А RECORD ж ғғ 
КЕМ 


CALL -934 : REM CLEAR SCREEN 

PRINT : PRINT "READ А RECORD" : PRINT 

PRINT "WHICH RECORD NUMBER (0 TO STOP)"; 

INPUT R 

IF R<1 THEN 300 : REM RETURN TO MAIN MENU 

IF КОМ THEN 2200 : REM RECORD DOES NOT EXIST 

PRINT 0%; "КЕАП RANDOM.R"SR = КЕМ PREFARE TO READ RECORD 
INPUT BS : REM READ THE DATA 

PRINT П% : REM CANCEL READ COMMAND 

PRINT =: PRINT BS : PRINT : REM DISPLAY THE DATA 

сата 2400 : REM ASK FOR ANOTHER RECORD NUMBER 

REM 

REM # s # + + АПП à RECORD зын 

КЕМ 

CALL -F36 : КЕМ CLEAR SCREEN 

PRINT : PRINT "ADD А RECORD" : PRINT 

PRINT "NEXT RECORD NUMBER = "3M+1 

PRINT : PRINT "ENTER DATA FOR RECORD "sM-*1 

PRINT "(PRESS [RETURN] NOW TO STOF ADDING)" 

INPUT BS : КЕМ GET USERS RESPONSE 

IF BS = "" THEN ЗОО : REM QUIT IS JUST CRETURNI 
PRINT 0%; "WRITE RANDOM, К": М+1 : REM PREPARE To WRITE 
PRINT BS : REM SEND DATA ТП FILE 

М = М + 1: REM INCREMENT LAST RECORD NUMBER 

PRINT "WRITE RANDOM, RO" : REM PREPARE TO WRITE RECORD 


PRINT M : REM STORE UPDATED VALUE 

PRINT П% : REM (CANCEL WRITE COMMAND 

GOTO 3500 : REM LOOP FOR ANOTHER RECORD 

REM 

REM s s # # # CHANGE А RECORD HoH dE EE 
REM 

CALL -936 : REM CLEAR SCREEN 

PRINT : PRINT "CHANGE А RECORD" : PRINT 

PRINT "CHANGE WHICH RECORD (О ТО STOP)": 

INPLIT R : 

IF R<1 THEN 300 : REM RETURN TO MAIN MENU 

IF R>M THEN 4600 : REM TRY AGAIN IF RECORD МОТ ON FILE 
PRINT I$:"READ RANDOM.;R"SR : REM PREPARE ТО READ 
INPUT B$ : REM READ THE RECORD 

PRINT D$ : REM CANCEL READ СОММАМП 

PRINT : PRINT BS : PRINT : REM DISPLAY THE DATA 
PRINT "ENTER THE NEW DATA" 

PRINT "(PRESS CRETURN] NOW TO CANCEL CHANGES)" 
PRINT 

INFUT C$ : REM GET USER^S RESPONSE 

IF СФ>"" THEN 6200 : REM BRANCH IF NEW DATA 

PRINT "RECORD "sks" UNCHANGED ! ' !'" : REM LOOP IF 
GOTO 4300 : REM NO CHANGES DESIRED 

PRINT D$:"WRITE RANDDOM.R":R : REM PREPARE TO WRITE 
PRINT C$ : REM STORE CHANGED DATA 
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6400 PRINT DS : КЕМ CANCEL WRITE COMMAND 

6500 GOTO 4800 : REM LOOP FOR ANOTHER RECORD TO CHANGE 
65950 КЕМ 

6600 REM * X X # # LIST ALL RECORDS + ME H + 

4650 REM 

6700 CALL -9234 : REM CLEAR SCREEN 

6300 PRINT PRINT "LIST ALL RECORDS" : PRINT 

649700 R 20 REM RESET THE COUNTER 

7000 R=R 1: REM INCREMENT THE COUNTER 

7100 IF R > M THEN 7700 : REM STOP AFTER LAST RECORD 
7200 PRINT 0%; "READ RANDO .R":R : REM FREPARE TO READ 
7300 INPUT BS : REM READ "HE DATA 

7400 PRINT "RECORD NUMBER : "ЗК : REM DISPLAY RECORU NUMBER 
7500 PRINT BS : PRINT : REM DISPLAY RECORD’S DATA 
7600 GOTO 7000 : REM LOOP FOR NEXT RECORD 

7700  FRINT ПФ : REM CANCEL READ COMMAND 

73800 PRINT : PRINT "+ + s # END-OF-FILE" : КЕМ PRINT 
ЕСПЕ MESSAGE 

7900 PRINT “PRESS RETURN TO CONTINUE": : REM REQUEST 
RESFUNSE 

8000 INPUT B$ : REM GET USER“S RESPONSE 

8100 GOTO 300 : REM RETURN TO MAIN MENU 


Mo es 


8150 REM 
9200 REM # s s # # STOP PROGRAM # t t ++ + 
2290 КЕМ 


8300 PRINT D$:"CLOSE" : REM CLOSE THE FILE 

8400 CALL -7234 : REM CLEAR SCREEN 

8500 FOR Ісі TO 24 : PRINT : NEXT I : REM MOVE ТО BOTTOM 
LINE 

8600 PRINT "PROGRAM COMPLETE.” 

8700 END 


ТНЕ ВҮТЕ РАНАМЕТЕН 


Byte is another useful random-access file parameter. The byte parameter is used 
with the READ, WRITE, and POSITION commands to move the pointer to the 
specified byte (character) within any selected record. А comma and the letter B 
may be added to a READ, WRITE, or POSITION command. The record parameter 
must be present with the byte parameter. Here is an example: 


REAM FILENAME; К19- ЕЗ 


In this example, reading will begin at the fourth byte in the 20th record. 
(Remember, the first byte is byte number O.) The byte parameter can move the 
pointer backward or forward within the record. 

If you are going to use the byte parameter, records must have an exact data 
format. You must know the byte position of each field within the record, or you 
will probably end up with meaningless data. 

When using the byte parameter with the POSITION command, remember that 
POSITION cancels any prior READ or WRITE command. You could execute a 
READ or WRITE command that includes a record parameter, then use POSITION 
to move forward to the correct field. But you must then execute another READ or 
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WRITE, since POSITION cancels the prior READ or WRITE command. 

POSITION will only move the pointer forward to another field in the current 
record. Within that field, the byte parameter allows you to reference subfields, 
one character at a time. 


OTHER DOS COMMANDS 


There are a few commands which have not been explained yet. These commands 
are EXEC, MAXFILES, TRACE, MON, and NOMON. 


EXEC 


EXEC is a very special command. EXEC allows you to turn contro! of your Apple І! 
over to a text file. The EXEC command looks like this: 


EXEC FILENAME,R4,S5,02,V23 


The R parameter is similar to the POSITION command's record parameter. It 
refers to the relative field number of the EXEC file where processing should begin. 
Since EXEC opens the file and places the pointer at the beginning of the EXEC file, 
the R parameter refers to an absolute field number within the file. RO is the default 
condition, which starts execution at the beginning of the file. R1 starts execution 
at the second field. 

The relative record, slot, drive, and volume specifications are all optional and 
can occur in any order. 

When EXEC is issued, the file specified is opened, then implicit READ and 
INPUT statements take place. The first line in the file is retrieved if no R parameter 
is present. If R is present, then the line specified by R is retrieved. 

The retrieved line is treated as if it had been typed on the keyboard in immedi- 
ate mode. If the line is meaningless garbage, you will see the message ?SYNTAX 
ERROR or *** SYNTAX ERR. If itis a valid program line, like: 


100 PRINT "THIS ІЗ A TEST" 


it will be stored in memory, as if you had just typed it. If it is a direct command, 
such as LIST or RUN, it will be executed. 

After action occasioned by the first line is completed, the next line is read and 
acted upon. This continues until the end of the file has been reached; at that time 
control of the Apple ІІ returns to the keyboard. 

Suppose a text file called BUBBA contains these lines of text: 


PRINT "I HAVE CONTROL OF YOUR APPLE ! ' '" 


100 GR 

200 FOR І=0 TO 39 
300 FOR J=O TO 3% 
400  COLORZSRNICO)3 1 5 
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500 PLOT I,J 

400 NEXT J 

700 NEXT I 

800 FOR Ісі ТП 5000 : NEXT I 
900 TEXT : CALL -934 

999 END 

LIST 

FOR Ісі TO 5000 : NEXT I 

RUN 

NEW 

PRINT "FINISHED.  HERE^S YOUR DISK CATALOG: " 
CATALOG 


When you type the command: 
EXEC BUBBA 


several things will happen. First a message will be displayed. Then Applesoft will 
be invoked. Next, a short program is entered into memory and listed. After a brief 
pause the program is RUN, then erased from memory. Another message is dis- 
played, followed by the catalog of the currently selected disk. 


Notes on EXEC 


EXEC has several interesting kinks you should know about. 

Only one EXEC file may be open at any one time. If a file which is being 
accessed by an EXEC command contains an EXEC command, the first file is 
closed and the second file takes control. 

After the EXEC file runs a program, the next EXEC file field (ie. line) is 
executed. If the program is aborted with Crrat-C, the EXEC will usually not con- 
tinue. 

If a program run by the EXEC command contains an INPUT statement, the 
input is taken from the next field in the EXEC file. That causes a problem if the 
next field is an immediate mode DOS command (not a program line). The com- 
mand will be executed instead of being accepted as INPUT data. 

If a program executes a CLOSE command, or if the EXEC file contains an 
immediate mode CLOSE command, the EXEC file will not be closed. 


Using EXEC to Convert a Program 
from One BASIC to the Other 


EXEC can be used to convert programs between Integer BASIC and Applesoft. 
First store the program as a text file. You can do this by adding a few lines to the 
program to create the text file, execute a WRITE command, then list the program. 
The listing goes into the text file. Here are the necessary statements: 


1 ПФ = "": PRINT 0%; "ОРЕМ FILE": FRINT 0%; "ИКІТЕ FILE" 
2 LIST 10,32767 

з PRINT ПФ: "CLOSE": END 

10 REM YOUR PROGRAM BEGINS HERE 
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When you run the program, only lines 1, 2, and 3 are executed. They will open a 
file and store the program listing in it. When this finishes, you can change to the 
other BASIC (with FP or INT, for example). Then type: 

EXEC FILE 
The old program lines will be loaded from the disk into memory. Now you must 
edit the program to correct the parts that don't conform to the rules of the new 
language. 


MAXFILES 


MAXFILES allows you to specify the maximum number of files which may be 
open at any one time. Each file has 595 bytes of memory reserved for its use as a 
buffer. There are two 256-byte sections in each buffer, one for reading and the 
other for writing. The remaining 83 bytes are used for housekeeping information, 
such as the track/sector list. 

When a file is opened, or a disk operation such as CATALOG or LOCK occurs, 
DOS reads 256 bytes of information from the disk and places it in a buffer. If the 
information has been changed and needs to be written back to the diskette, 256 
bytes are copied from the buffer and stored on the diskette. 

The following example specifies eight files maximum: 

MAXFILES & 


The number of files must be an integer from 1 to 16. When DOS is booted, three 
buffers are allocated. MAXFILES may be set higher if you intend to use more than 
three files simultaneously. MAXFILES may be set lower if you need those extra 
bytes of memory for your application. 

One buffer is used just to execute any of the following DOS commands: 


APPEND FP POSITION 
BLOAD INIT READ 
BRUN INT RENAME 
BSAVE LOAD RUN 
CATALOG LOCK SAVE 
CHAIN MAXFILES UNLOCK 
CLOSE MON VERIFY 
DELETE NOMON WRITE 
EXEC OPEN 


Thus, if you have opened disk files up to the limit and then issue the CATALOG 
command, the error NO BUFFERS AVAILABLE is returned. No buffer is required 
for commands used outside of the DOS context, however (e.g., cassette LOAD). 

When MAXFILES is changed, Integer BASIC programs are erased and 
Applesoft strings become garbled. Therefore, execute MAXFILES before loading 
or running a program. 

MAXFILES may be executed within Applesoft programs if preceded Бу а Crat- 
D character in a PRINT statement. MAXFILES will cause GOTO, GOSUB, and other 
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instructions to malfunction unless it is the first statement in the program. In order 
to avoid having strings clobbered, use MAXFILES as follows: 


11 REM FIRST ISSUE MAXFILES COMMAND 


ы 
hà 


PRINT CHR$(4):"MAXFILES ©" 


J3 REM REGULAR PROGRAM BEGINS HERE 


өз 


1 


4 


ОФ=СНКФ (4) : КЕМ CTRL-D CHARACTER 


You can only use MAXFILES in Integer BASIC іп the context of an EXEC file. For 
example, the EXEC file contains three psuedo-immediate mode statements: 


MAXFILES З 
LOAD PROGRAM 
RUN 10 


It is invoked in a program as follows: 


ә PRINT 1%; "EXEC MXF": REM SET MAXFILES 
CONTINUE AT LINE 10 
10 REM PROGRAM BEGINS НЕКЕ 


USING DOS DEBUGGING AIDS 


Since programs which access disk files are usually somewhat complex, DOS has 
three commands that help you debug programs: MON, NOMON and TRACE. 


MON 


MON is short for monitor. MON allows you to monitor the information going to 
and coming from the disk. MON uses three parameters. The following example 
shows all three: 

MON C.I.U0 


MON parameters specify the type of information to be displayed. C causes com- 
mands to the disk to be monitored. | causes input from the disk to be displayed. O 
causes output to the disk to be displayed. 

The parameters may appear in any order, and in any combination. At least one 
parameter must be present or the command will be ignored. 

MON will remain in effect until a NOMON, INT, or FP command is executed, or 
DOS is rebooted. 


NOMON 


NOMON cancels the effect of the MON command. NOMON uses the same three 
parameters MON uses, but the NOMON parameters specify which data is not to 
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be monitored. For example, assuming MON І,О,С has been issued, the command: 
NOMON C 


will cancel monitoring of output to the disk. Input from the disk and DOS Com- 
mands will continue to be displayed. 


Using the TRACE Command 


The TRACE command (see Chapter 4) is used when debugging programs. But 
since TRACE prints line numbers with no carriage return, DOS commands 
become concatenated to the line number, and ignored. The remedy for this is sim- 
ple. A carriage return should be output prior to each DOS command. To do this, 
change the line: 


100 D$ = CHR (4): REM CTRL-D 
to read: 
100 D$ = CHR (13) + CHR$(40: REM RETURN + CTRL: 


Then, whenever PRINT D$ occurs, the CrRL-D character will be preceded by a car- 
riage return, separating it from the traced line numbers. 

Another problem exists, though. If a WRITE command is in effect, all those line 
numbers will be stored in the file. (Sorry, no way around this one.) 


MACHINE LANGUAGE 
(BINARY IMAGE) DISK FILES 


The Disk Il supports machine language and binary image (graphics) files. These 
files are shown with the letter B as the file type code in a disk catalog. 

Both low-resolution and high-resolution images can be stored on diskettes for 
later recall and display. 

Machine language programs can be loaded and executed directly, or they may 
be called by BASIC programs using the CALL statement or USR function. 

DOS has three commands which are specifically designed for binary files. They 
are BSAVE, BLOAD, and BRUN. The effect of each command is the same as its 
nonbinary equivalent (BSAVE=SAVE, BLOAD=LOAD, BRUN=RUN). 


BSAVE 
BSAVE, as the name implies, saves a binary image on the disk. Here is an example: 
BSAVE FILENAME, 6378, L21; 56, DŻ, V6 


Note that there are two parameters not found on other DOS commands. Note 
also that these parameters are not optional; they must be specified. The slot, 
drive, and volume parameters are optional, as usual. 
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Parameter A is the address parameter; it refers to the starting memory address 
of the binary image to be saved. The address may be either decimal or hex- 
adecimal constants. Hexadecimal values must be preceded by a dollar sign ($). 
Decimal values must be in the range O to 65535. Negative values are prohibited. 

The L parameter specifies the /ength of the binary image to be saved. The 
length is the number of bytes in the image. It may be specified as a decimal or 
hexadecimal number, with hexadecimal values preceded by a dollar sign ($). The 
length must be in the range 1 through 32767 or a SYNTAX ERROR will be gener- 
ated. 32767 bytes is the largest size DOS can store as a single field. Two BSAVE 
statements must be used to store more than 32767 bytes. 

If the memory locations in the range specified do not physically exist, no error 
will be returned. It is not very useful to specify a location outside of the installed 
range on your Apple Il (e.g., 49151 or $BFFF оп a 48K system). 


BLOAD 


BLOAD retrieves the contents of binary files and loads them into memory. The 
BLOAD command looks like this: 


BLOAD FILENAME, 3728,L21; 36, IZ: V6 


The address parameter is optional with the BLOAD command. If it is absent, the 
image will be loaded beginning at the address specified when the image was 
saved. 

Machine language programs may not function properly if they are loaded into 
the wrong memory addresses. 

Unlike the LOAD command, BLOAD will not erase programs or data values 
unless they reside in the memory locations where the image will be stored. Only 
those locations within the BLOAD range are affected; no other memory values are 
changed. 

No error will be returned if you specify read-only memory (ROM) locations as 
part of the BLOAD range. The ROM locations will be unchanged, of course. 


BRUN 


BRUN is identical to BLOAD except that after the file has been loaded, BRUN 
executes a machine language JMP (jump) instruction to the starting address. If no 
address was specified, the jump will be to the address from which the image was 
saved. The following is a BRUN example: 

ERUN FILENAME, А278,121, 54, 02,34 


Never use BRUN with a graphic image, as the results are unpredictable. 


6 


Graphics and Sound 


The Apple ІІ has capabilities for color video graphics and sound generation. 
Together, these features add another dimension to the programs you use, as well 
as those you might write yourself. This chapter is suited for the novice who may 
have just learned BASIC (perhaps by reading this book), as well as the assembly 
language programmer. Graphics are not difficult to master, especially in a high- 
level language. The Apple 1 Monitor, with its built-in machine language 
subroutines, helps the assembly language programmer use graphics and the 
Apple ll onboard speaker even more. Once you finish this chapter you will have 
enough solid working knowledge of these features to start using them in pro- 
grams you write. 


LOW-RESOLUTION GRAPHICS 


The Apple ІІ has two separate areas of memory available for low-resolution 
graphics. These two areas are called pages. Either low-resolution page can appear 
on the display screen as a graphics display 40 columns across by 48 rows, as 
shown in Figure 6-1. 

Each coordinate (intersection of a row and column) appears as a small rec- 
tangle on the display screen. Each page contains 1,920 coordinates (40 columns 
times 48 rows), and you can assign any one of 16 colors to each coordinate on a 
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FIGURE 6-1. Low-Resolution Graphics Screen 


page. Table 6-1 shows the hues which are available. You don't have to know the 
inner workings of the Apple Il in order to use low-resolution graphics; a working 
knowledge of programming in BASIC (plus a little coordinate plotting) is sufficient 
to get you started. 


SETTING UP THE GRAPHICS PAGE 


The page dedicated to low-resolution graphics also doubles as the text page for 
the Apple 11. When using BASIC, you switch to graphics mode from text mode by 
using the statement: GR 


Once this statement executes, the display screen goes black except for four 
lines at the bottom of the screen which hold text. This lower area of the screen is 


TABLE 6-1. Low-Resolution Graphics Colors 


Black Brown 
Magenta Orange 
Dark Blue Gray +2 


Purple Pink 

Dark Green Light Green 
Gray +1 Yellow 
Medium Blue Aqua 

Light Blue White 
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called the text window. With the text window at the bottom of the screen, space 
exists for 40 of the 48 rows available in low-resolution graphics mode. You сап 
use this statement more than once in a program, even when you are in low-resolu- 
tion graphics mode, as a means of clearing the screen. 


Full-Screen Graphics 


After executing the GR statement, you can eliminate the text window to allow the 


last eight lines of graphics by entering: 


РОКЕ -16302.0 
қалы. ым 2 
The text window disappears, replaced Бу graphics. 
SS 


Restoring the Text Window 


If the Apple Il is in full-screen graphics mode, you can restore the text window in 
two ways. To clear the graphics screen and restore the text window at the same 
time, use the GR statement. If you want to restore the text window without alter- 
ing the first 40 rows of graphics, enter the statement: 
POKE -16301,0 
Once executed, this statement reopens the text window at the bottom of the 
screen. 


Going Back to Full-Screen Text 
ht M st eee а Й 


To leave the low-resolution graphics mode and return to the full-screen text 


mode, this BASIC statement: 
TEXT 


resets the display from graphics to characters. While the GR statement clears the 
screen when it executes, TEXT does not. Remember that text and graphics both 
use the same area of memory. Once this statement executes, you will probably 
see a screen full of odd characters; this is because the Apple ll is now interpreting 
graphics data in memory as text. Clear the text screen with the Esc- Q key 
sequence, with the CALL —936 BASIC statement, or in Applesoft, with the HOME 
command. 


GRAPHICS PROGRAMMING STATEMENTS 


Both Integer BASIC and Applesoft recognize low-resolution graphics commands 
to plot single coordinates on the screen, change the color used for plotting, and 
draw vertical or horizontal lines of varying lengths. These commands work only on 
low-resolution graphics page 1 (also called the primary page). If you use page 2, 
you eliminate many of these timesaving statements and must resort to such non- 
descriptive statements as PEEK, POKE and CALL. 
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The COLOR Statement 


In Table 6-1, each color listed has a corresponding number from O to 15. It is this 
number which you use in a COLOR statement to set the current low-resolution 
hue. For example: 

COLOR=13 


sets the drawing color to yellow. If you neglect to select a color, the Apple 1! 
chooses black, equivalent to COLOR-O, as the default color. Although you can 
specify a color number as high as 255 without generating a syntax error, COLOR 
only pays attention to the low-order nybb/e of the color number you select. 
Therefore, if you enter COLOR=222 (equal to DE hexadecimal), it will evaluate to 
COLOR=15 (equal to OE hexadecimal). 


The PLOT Statement 


This BASIC statement places a single graphics dot — actually a small rectangle — 
оп the Apple Il display screen at the coordinates you specify. 
The statement: 
PLOT 23,18 


illuminates the graphics point at the 24th row and 19th column in the hue 
selected by the latest COLOR statement executed. This row number ranges from 
O to 47, and the column value from O to 39. If you exceed these limits in a PLOT 
statement, you will get an error message, and your program will stop. As with any 
low-resolution graphics statement (except GR), you can replace literal expressions 


with variables: 
PLOT Ү/2+12, Х-4 


А Plotting Example 


The following Integer BASIC program uses all of the low-resolution graphics 
statements discussed so far in this chapter. The object is to plot a diagonal line 
from the upper lefthand to lower righthand corners of the screen. 


10 REM DRAW А DIAGONAL LINE 
11 REM ACROSS HE LOW-RES SCREEN 
zo GR 
зо COLOR= RNE (14) 
40 FOR Ү=0 TO 39 
ЕО PLOT Y,Y 
60 NEXT Y 
70 GOTO 30 
The display screen will look like Figure 6-2, except that the diagonal line 
changes colors randomly. 
To convert this program to Applesoft, change line 30 as shown below. 


Ж зо COLOR= КМО (16) ж 16 
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FIGURE 6-2. Low-Resolution Plotting Example 


Drawing Horizontal Lines 


The HLIN command allows you to draw lines of varying lengths from left to right 
on the low-resolution graphics page. This statement: 


HLIN 0,39 АТО 


draws a horizontal line at the extreme top of the screen, from the left margin to 
the right margin. HLIN stands for horizontal line. The general format of this state- 
ment is to enter the lefthand column followed by a comma, the righthand column 
to draw to (39 in this case), the word AT, and the row on which to draw the line. 

The lefthand and righthand column parameters cannot be negative and must 
be less than 256; the righthand column cannot be smaller than the lefthand col- 
umn parameter. The parameter following AT cannot be negative or larger than 48. 
If any of the parameters exceed the limits, an error message appears, stopping 
execution. If you specify column numbers greater than 39 in the HLIN statement 
in Integer BASIC, you will receive unpredictable results. Applesoft gives you an 
error message. For example, execute the statements: 


10 GR 
20 COLOR-12 
30 HLIN 45,100 АТ O 


In Integer BASIC, they cause two green bars to display. The first bar is not on 
row O (the highest line on the display) as it should be, and the bar continues 
several lines down on the screen. It is rarely a good idea to let these values exceed 
actual locations on the low-resolution screen. 
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Drawing Vertical Lines 


The VLIN (for vertical line) statement draws a line in the selected color, from one 
row to another in a specified column. 
For example: 


VLIN 12,30 АТ 33 


draws a line from row 12 down to row 30 at column 33. The parameter values for 
VLIN are identical to those for HLIN: the first and second expressions must be 
integers between O and 255 inclusive, the second parameter cannot be less than 
the first, and the last parameter (corresponding to the column number) must be 
between O and 39 inclusive. If any of these parameters is out of the ranges 
allowed, an error message displays on the Apple ll screen. 


Using HLIN and VLIN 
in a Program 


Another program (listed below) helps explain the use of HLIN and VLIN. Here, ran- 
dom lines draw in random colors on the screen. To stop the program, press CTRL- 
C. 


10 REM LOW-RES HLIN AND VLIN DEMO 

20 GR = REM USE GRAPHICS PAGE 1 

ЗО POKE -146302,0: REM SET FULL-PAGE 

40 CALL -1998: REM CLEAR ALL 48 ROWS 

SO REM BEGIN PROGRAM 

60 COLOR= RND (16): REM SELECT RANDOM COLOR 
70 НІМ О, RND (40) АТ RND (48) 

SO COLOR= RND (16) 

90 VLIN О, RND (48) АТ RND (40) 

100 GOTO 60 


The SCRN Statement 


The SCRN statement is a bit more subtle than the other low-resolution graphics 
statements. Suppose you want the computer to figure out what color is displayed 
at a certain point on the screen. SCRN does this. This statement: 

X=SCRN(12, 24) 
assigns the color number of the coordinates in parentheses (in this case, the 13th 
row and 25th column) to the variable X. The color passed back to the variable is 
numbered O through 15; the number corresponds to one of the low-resolution 
colors shown in Table 6-1. For example, if you enter the following immediate 
mode statements: 

GR 

COLOR=14 

PLOT 12,12 

PRINT SCRN (12,12) 


the Apple ЇЇ responds: 
14 
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* 


This statement may be very useful to you when you write advanced low- 
resolution graphics programs. 


HIGH-RESOLUTION GRAPHICS 


The most fetching aspect of the Apple Il computer is its high-resolution graphics 
capability. Like low-resolution graphics, you have two separate areas or pages 
available for use. However, this is where the similarity ends. Resolution in this 
mode is 280 horizontal positions by 192 vertical positions, an increase over low- 
resolution by 7 times on the horizontal axis and 4 times on the vertical axis. 
Although fewer colors are available for you to use in high-resolution graphics 
mode, you can plot much finer lines on the screen. 

Built-in high-resolution graphics functions are only available in Applesoft. 
Integer BASIC has no intrinsic commands of this kind. However, no matter what 
language you use on the Apple Il, the computer always has the capability for high- 
resolution graphics because the Apple ll uses part of its memory to store high- 
resolution dots, lines, and shapes and includes built-in programs which interpret 
and display this memory on the TV screen. Certain Applesoft statements auto- 
matically use the built-in programs and screen memory; we will discuss them first. 
Later in this section you will see how to incorporate high-resolution graphics into 
an Integer BASIC program as well. As you read further, you will discover some 
high-resolution tricks achievable ол/у with Integer BASIC. 


WHICH PAGE SHOULD YOU USE? 


There are some difficulties in using high-resolution graphics, and they involve 
how much memory your Apple ІІ has. If you have firmware Applesoft (i.e., in ROM, 
or the Apple Il Language System), you can use high-resolution page 1 /Ғ your 
computer contains more than 16K, and you can use page 2 /f your Apple ЇЇ has 
24K of memory or more. Add 12K to the minimum memory if you will use the 
Disk Operating System (DOS) and Applesoft high-resolution graphics at the same 
time. 

If you use the versions of Applesoft from cassette or disk, you cannot use 
high-resolution page 1, as it is used to hold part of the Applesoft interpreter. If you 
try to use high-resolution page 1, you will corrupt or entirely lose the ability to pro- 
gram in Applesoft, as well as the actual BASIC program currently in memory. You 
can use high-resolution page 2 if your Apple Il has at least 24K, or 36K if you 
want to have DOS in memory at the same time. 


Setting Aside High-Resolution 
Graphics Memory 


Applesoft does not automatically protect memory for high-resolution graphics. 
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As a program becomes larger, either by adding statements or more variables, the 
chances of destroying graphics pages increase. The way to solve this problem is 
to set two memory pointers, НІМЕМ: and (ОМЕМ:, to values which will protect 
the high-resolution graphics page or pages you use. These pointers act as bound- 
aries which your program will not cross, thus yielding up to two areas of memory 
which you can use freely. 

HIMEM: and LOMEM: usage differs in Applesoft and Integer BASIC. Check 
these differences in the BASIC compendium, located in Chapter 8. Also, Figure 
G-1 in Appendix G depicts memory usage pictorially. The following three 
paragraphs will be easier to follow if you refer to it. 

If you intend to use high-resolution page 1 (remember that you must have firm- 
ware Applesoft to do this), and you only have a 16K Apple Il, set HIMEM: to 8191 
and leave LOMEM: alone. This keeps your Applesoft program below memory 
location 8191, which is a significant restriction but one that is unavoidable since 
you need 8K for high-resolution screen memory. If you want to use high-resolu- 
tion page 1 on an Apple Il with more than 16K, you may prefer to leave HIMEM: 
alone and set LOMEM: to 16384. This places your Applesoft program above 
high-resolution page 1. CAUT/ON: Do not use this latter scheme in conjunction 
with DOS unless you have at least 32K of memory. Otherwise, stick to the first 
scheme, which keeps your Applesoft program below page 1. 

If you intend to use high-resolution page 2 (possible only with 24K or more), 
set LOMEM: to 24576, or set HIMEM: to 16383 and leave LOMEM: unchanged. 
By adjusting LOMEM:, you place your Applesoft program above high-resolution 
page 2. In order to use DOS at the same time, you need at least 48K of memory. If 
you adjust HIMEM: instead, your program resides be/ow high-resolution page 2. In 
this latter case, if you are using a nonfirmware Applesoft interpreter (from 
cassette or disk), your Applesoft program will have to squeeze in above the 
interpreter and below high-resolution page 2, a tight fit. 

If you plan to use both pages for high-resolution graphics (possible only with 
firmware Applesoft), set LOMEM: to 24576 or set HIMEM: to 8191. If you put 
your Applesoft program above the high-resolution pages by adjusting LOMEM: 
and leaving HIMEM: alone then you will need at least 48K in order to use DOS and 
still have a meaningful amount of memory for your Applesoft program. 


SETTING UP THE GRAPHICS DISPLAY 


Although two pages are available for high-resolution graphics, cassette and disk 
Applesoft use part of high-resolution page 1 for storing the language itself (the 
interpreter). If you have an Apple Il Plus or a standard Apple Il, either with the 
Applesoft Firmware card or the Language System, you can use page 1 without 
adversely affecting BASIC. For the sake of compatibility with other Apple ll com- 
puters, you may want to use high-resolution page 2 anyway. 
In Applesoft, the statement: 
HGR 
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clears and then displays high-resolution page 1, with a four-line text window at 
the bottom of the screen. You can have both graphics and text on the screen in 
this mode by using PRINT statements in Applesoft to display text in the text win- 
dow. However, once the Apple ІІ executes HGR, the screen will show only 160 of 
the 192 high-resolution horizontal lines available. In order to show full-screen 
graphics, perform а POKE – 16302,0 after HGR. This will eliminate the text win- 
dow and replace it with the remaining 32 lines of graphics. 
To display high-resolution page 2, use the statement: 


HGR2 


Execution of HGR2 erases and then displays all 192 lines of high-resolution 
page 2, leaving no text window at the bottom of the screen. To open the text win- 
dow at the bottom of the screen, perform a POKE —16301,0 after HGR2. The 
text window is more difficult to use with high-resolution page 2, however. The 
text which appears in the window is from the secondary text page. BASIC can 
only access this page via POKE statements (not via PRINT), which is quite limiting. 
Furthermore, the secondary text page is not protected from overwriting by BASIC 
as is text page 1, so you will need to set LOMEM: to 3071 or greater. 


ALTERNATIVES TO HGR AND HGR2 


A principal disadvantage of using HGR and HGR2 is that executing either of these 
statements clears the high-resolution page selected whether you like it or not. 
Moreover, these statements are not available in Integer BASIC. You can use PEEK, 
POKE, and CALL statements to set up the graphics pages more flexibly, and you 
may find them useful no matter what language you use on the Apple Il. 


Another Way to Set Up 
the Graphics Display 


It is possible to go into high-resolution graphics mode without erasing the display 
screen. You can liken this procedure to flipping a series of switches. In theory, you 
are doing just that to a set of reserved memory locations called soft switches, 
which reside at memory locations —16304 through —16297 ($CO50 through 
$С057). Figure E-1 in Appendix E illustrates the available switches. In order to 
keep these statements compatible with both Integer BASIC and Applesoft, we 
use the negative integer representation of these memory locations (e.g., - 16304 
instead of 49231). 
To display high-resolution graphics page 1 without erasing its previous con- 

tents, perform the following statements: 

FOKE -16304;0 Sets graphics mode 

POKE -16297;.0 Sets high-resolution mode 


POKE -16300,0 Selects high-resolution page 1 
(Only necessary if switching 
from high-resolution page 2) 
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Try these statements in immediate mode as an experiment. 
To display high-resolution graphics page 2 without erasing its previous con- 
tents, enter the following statements: 


POKE -16304,0 Only necessary if graphics 
mode has not already been set 
POKE -146297,0 Only necessary if high-resolution mode 
has not already been set 
POKE -16299,0 Selects high-resolution page 2 


Normal BASIC After 
High-Resolution Graphics 


In Integer BASIC, the TEXT and GR statements may be insufficient to completely 
reset the display screen. If you have been using page 2 graphics, you must 
explicitly reselect page 1 with a POKE —16300,0 statement. Otherwise you will 
see page 2 of the text/low-resolution screen memory. This can be especially con- 
fusing in text mode. The keyboard appears to be dead because everything you 
type goes into page 1 screen memory, while you are looking at page 2 screen 
memory. 

The GR statement does not switch from high-resolution to low-resolution 
graphics in Integer BASIC. It only selects graphics mode with a four-line text win- 
dow (as opposed to all-text mode). You must explicitly select low-resolution 
graphics with a POKE —16298,0 statement. 


Clearing the High-Resolution Pages 


If you use high-resolution graphics under Applesoft, HGR or HGR2 will clear the 
selected page whenever the statement is executed. However, under Integer 
BASIC there is no single statement which performs this function. The following 
subroutine uses a built-in Monitor function to clear the high-resolution screen: 


18990 REM 3H EE IEIERETEIEREREREREREREREAETEHEHE E 
19991 REM + CLEAR HI-RES SCREEN 3 
18992 REM # (USES MONITOR^S "MOVE" ж 
18993 REM # SUBROUTINE AT $FE2C + 
18994 REM ж TO MOVE DATA QUICKLY ж 
18995 КЕМ # THROUGH THE HI-RES AREA)* 
18996 REM + 

19997 REM % SET PAGE-1 OR 2: THE % 
18998 КЕМ # ROUTINE DOES THE REST. ж 
18999 REM Hits eH ынны» 
19000 START=32 

19010 IF PAGE-2 THEN START-264 

19020 POKE 60.0 

19030 POKE 61; START 

19040 РОКЕ 62-254 

19050 POKE 63,START+33 
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19060 POKE 66,1 

19070 POKE 67,START 

19080 POKE -16304,0 

19090 POKE -16297,0 

19100 IF FAGE-1 THEN POKE -16300,0 
17110 IF PAGE=2 THEN РОКЕ -16299,0 
19120 POKE START#256,0 

19130 CALL -468 

19140 RETURN 


This BASIC subroutine moves zeros throughout the high-resolution graphics 
page you select. If the variable PAGE is set to 1, the subroutine clears page 1; if 
set to 2, page 2 is cleared. This subroutine only works in Integer BASIC; however, 
don't consider that a disadvantage. Applesoft performs this function much more 
efficiently with HGR or HGR2. 


HIGH-RESOLUTION COLORS 


Eight color choices are available in high-resolution mode, but there are only four 
different colors available, plus black and white. Table 6-2 shows these colors and 
their corresponding numbers (used when selecting the color). 


The HCOLOR Statement 


The Applesoft HCOLOR statement selects one of the eight colors available for 
high-resolution use. Unlike the COLOR statement in low-resolution graphics 
(which will allow you to specify numbers higher than those allocated to colors), 
HCOLOR will not accept a color number greater than 7. If you do specify an out- 
of-range color, your program will abruptly stop with an ?ILLEGAL QUANTITY 
ERROR message. HCOLOR does not change the color of any graphics already on 
the high-resolution screen, nor does it have any effect on low-resolution graphics. 


Setting a High-Resolution Background Color 


With a slight modification, the subroutine presented earlier which clears the high- 


TABLE 6-2. High-Resolution Graphics Colors 


Color Number Color Number 
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resolution screen will fill the entire screen with any one of the high-resolution col- 
ors. The subroutine below does this. Before calling the subroutine, assign the 
graphics page number to variable PAGE. Also, assign the high-resolution color 
number to variable HCOLR. The calling program must set the soft switches for 
high-resolution graphics mode. This subroutine works only in Integer BASIC. 


18990 REM заз HHA 
18991 REM SET BACKGRNLI COLOR: 
19992 REM 
18993 REM ж SET PAGE-1 OR 2: ж 

18994 REM +# ALSO SET HCOLR TO + 

18995 REM ж APPLESOFT EQUIVA- + 

18995 REM # LENT HI-RES COLOR, 

19997 REM i3 3 ESETERSEREREIESESETERERE JE IE AE HERE 

19000 START=32 

19010 IF PAGE=2 THEN START=44 

19020 POKE 60.0 

19030 POKE ,61; START 

19040 POKE 62,253 

19050 POKE 63,START+23 

19060 POKE 66.2 

19070 POKE 67, 5ТАКТ 

19078 Ү1=85:Х1=42 

19080 IF НСО К>О AND НСО К<>4 THEN 19090: X1=0: Y1=0 
19090 IF HCOLR<>3 AND HCOLR<>7 THEN 19100: X1=127:Y1=127 
19100 IF HCOLR-1 OR HCOLR-S THEN 19120 

19110 X3zX1:Xi1Yi1:Y1-X3 

19120 IF HCOLR«X4 THEN 17140 

19130 Yi1zYi1-*128: X1=X1+128 

19140 FOKE START#254, X1 

19150 POKE START#256+1,Y1 

19160 IF РАСЕсі THEN POKE -146300,0 

19170 IF PAGE=2 THEN POKE -146299,0 

19180 CALL -468 

19190 RETURN 


+ 
* 


PLOTTING POINTS AND LINES 


One powerful advantage in Applesoft high-resolution graphics is the ability to plot 
lines of any angle as well as individual points and horizontal or vertical lines. The 
HPLOT statement can be used in three ways: 


HPLOT 12,12 


This plots a single point on the currently selected high-resolution page at the 
intersection of the thirteenth row and thirteenth column, in the currently selected 
high-resolution plotting color. 

The second use of HPLOT is: 


HPLOT 0-0 TO 279,191 


This statement draws a diagonal line from the upper righthand to lower lefthand 
corners of the screen. Using HPLOT with two sets of coordinates as shown 
above, you can plot from one point to another on the screen. 
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The third type is more sophisticated: 
HPLOT 0,0 TO 279,0 TO 279,191 TO 0,191 TO 0,0 


This version of HPLOT only works on firmware versions of Applesoft. Cassette- 
based and disk-based Applesoft do not allow this form of HPLOT. Here you can 
define multiple plotting statements very easily. All segments are drawn in the 
same color. This can be quite useful if you want to draw a many-sided shape. 


Alternatives to HPLOT 


The subroutine listed below allows you to program high-resolution graphics in 
Integer BASIC, without having to switch pages. You may find this subroutine use- 
ful; however, it is rather slow because all calculations occur in BASIC. To use this 
subroutine, pass the X and Y coordinates of the point you wish to plot. Make sure 
that PAGE is set to the high-resolution page you want to use. It is up to you to set 
high-resolution, graphics, and full-screen graphics modes. This adds some flex- 
ibility. If you use this subroutine without first setting high-resolution mode, the 
subroutine will plot into high-resolution screen memory but will not change the 
screen display itself. Later, after the program finishes plotting in the screen 
memory, it can turn on high-resolution graphics with a series of POKE statements 
(as described earlier) and the high-resolution plotting that took place behind the 
scenes will suddenly be visible. This lets you program points on page 2 while dis- 
playing page 1 high-resolution graphics, and vice versa. 

20000 REM 3t 3t JE 3E 3E 3E 3E 3E 3E 3E HE E HE 3E 3E 3E 3E 3E TE EE 3E 30 

20001 REM # HI-RES INTEGER PLOT ж 

20002 REM ж ------------------- + 


20003 REM ж SET X=COL, Y=ROW, + 
20004 REM ж PAGE-1 OR 2: USES 3 


20005 REM # VARS Ү1.Х1. ХЗ + 
20006 REM © ЗЕЗЕЗЕЗЕЗЕЗЕЗЕЗЕЗЕЗЕЗЕЗЕ ЕЗЕТ 4E TE IE SEHE HE 
20007 REM 


20010 ҮІ=ҒАСЕ#8192: REM SET BASE ADDRESS 
20020 Y1=Y1+(Y/64)#40+(Y MOD 2) +1024 

20030 Yi1zY1*(Y MOD 64/85) +128+Х/7 

20040 X1= PEEK (Ү1): КЕМ READ IN THE HI-RES BYTE 
20050 X3-2 ^ (X MOD 7) 

20060 REM "OR" THE BYTE IN X1 WITH 

20070 REM THE BIT VALUE IN X3. 

20080 IF ХІ MOD (ХЗ ^ 2)<X3 THEN X1=X1+X3 
20090 POKE Ү1.Х3 

21000 Хіс PEEK (Y1) 

21010 X3=2 ^ (X MOD 7) 

21020 IF X1 MOD (Х3#+2) <ХЗ THEN X1=X1+X3 
21025 X322 ^ (X MOD 7) 

21026 GOTO 21100 

21030 РОКЕ Y1,X3 

21040 RETURN 

21100 РОКЕ ҮІ, ХЗ 

21130 RETURN 

25000 GOSUB 19000 
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An Integer BASIC High-Resolution Example 


The next program uses two of the subroutines recently introduced to plot points 
on the high-resolution screen. The game controls determine the coordinates to 
plot. By rotating the controls, you can sketch lines on the screen. 


10 REM THIS PROGRAM USES SPECIAL 
20 КЕМ SUBROUTINES TO CLEAR AND 
30 REM PLOT IN HI-RES GRAPHICS 
40 REM USE CTRL-C TQ END PROGRAM 
89 REM SET GRAPHICS MODE 
90 POKE -16304,0 
99 REM SET HI-RES GRAPHICS 
100 POKE -16297,0 
109 REM SELECT FULL-SCREEN GRAPHICS 
110 POKE -16302:0 
200 PAGE-2 
204 REM CLEAR HI-RES SCREEN MEMORY 
205 GOSUB 19000 
209 REM GET РОІМТ COORDINATES 
210 X= PDL (1) 
220 Y= PDL (0) 
229 REM PLOT HI-RES POINT 
230 GOSUB 20010 
239 REM GET MORE COORDINATES 
240 GOTO 210 
260 END 


For an interesting variation of this program, try using the subroutine which fills in a 
solid color on the screen instead of the clear-screen subroutine. 

Try improving the program by checking the game control pushbuttons with 
POKE statements, and clearing the screen each time a pushbutton is pushed. 


USING HIGH-RESOLUTION SHAPES 


Along with coordinate plotting and drawing, the Apple ІІ enables you to define, 
draw, and manipulate two-dimensional shapes in high-resolution graphics mode. 
This section describes how to create, design, and use a shape under Applesoft. 
Thorough as it may be, this section only begins to explore the creative possibilities 
open to you. 

If you have written any high-resolution graphics programs which plot 
geometric figures, you probably encountered some difficulty in manipulating 
those figures on the screen. For instance, you may want to rotate the figure on an 
axis, or make it appear larger or smaller on the screen. High-resolution shapes 
have this manipulation feature. 


DEFINING SHAPES 


High-resolution shapes require planning. Іп essence, you go beyond telling the 
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computer to draw a line from point À to point B. When you use shapes on the 
Apple ll, you describe the entire figure before instructing the computer to draw it. 
You define high-resolution shapes in a shape table, so called because it contains 
the coded characteristics of the figure to draw. The first step in defining a high- 
resolution shape is to draw the shape itself on paper. Take the example of draw- 
ing a square, which consists of four lines of equal length, each one at a right angle 
to the previous line drawn: 


ыы 


The shape table contains coded instructions to draw a figure; these instruc- 
tions are called p/ottíng vectors. Each vector describes movement up, down, left, 
right, or not at all, and also whether to draw on the screen or not. You can 
interpret each side of the square in the illustration above as a direction in which to 
draw: one up, one right, one down, and one left. This is the way Applesoft's shape 
manipulation routines look at figures. 

Figures are more difficult to draw if they contain diagonal lines or curves. A 
triangle, although it has one side less than the square, involves much more work 
because it contains at least one diagonal line. The broken lines in the illustration 
below indicate movement without any drawing (ghost vectors): 


| 
| 
| 
І 
v 
i 
] 
i 
i 
] 
! 


* > 


= 


Since you can only define a shape with vectors which move up, down, or side- 
ways, some shapes, such as circles, may not be worth approximating. In some 
cases it may be easier to draw complicated shapes using HPLOT rather than using 
shape tables. 


ASSEMBLING THE SHAPE TABLE 


The figure you drew on paper must go through a conversion to coded plotting 
vectors. This section tells you how to make the conversion. The next section pre- 
sents an Applesoft program that does the conversion for you. So you may skip t. 
the next section if you are not interested in all of the inner workings of shape 
tables. 
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Vector codes range in value from O to 7; each byte of a shape definition (part 
of the shape table) can hold up to three vectors. Table 6-3 shows the possible 
plotting vector codes. Once the shape is reduced to a set of vectors, the vectors 
can be placed in memory, where certain Applesoft commands can decode them 
and draw the shape. 

Pick a starting point on the shape. Make a list of the plotting vectors needed to 
construct the shape, using arrows (| — | —). List the vectors in order as you go 
around the shape (clockwise or counterclockwise, it doesn't matter). Mark any 
vectors to be plotted but not drawn (ghost vectors). Starting in the lower lefthand 
corner, our square corresponds to these vectors: 


[Direction [Plot 


1 Yes 
Yes 
Yes 


Now write the proper binary code next to each vector (use Table 6-3 to trans- 
late). This is what you should get: 


As shown in Table 6-4, each byte of the shape table contains three sections, 
each of which may contain a plotting vector. Notice that sections 1 and 2 contain 
three bits each, while section 3 only contains two bits. 


TABLE 6-3. Plotting Vectors and their ay Codes 


Move up without plotting 
Move right without plotting 
Move down without plotting 


Move left without plotting 
Move up with plotting 
Move right with plotting 
Move down with plotting 
Move left with plotting 
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TABLE 6-4. Shape Table Byte 


Movement bit 
Plot/No Plot bit 


By inspecting Table 6-3, you can see that some of the codes used for drawing 
are three-bit numbers. This is fine for sections 1 and 2 of each shape definition 
byte, each of which holds three bits. However section 3, because it only contains 
two bits, can only hold certain plotting vectors. The vectors allowed in section 3 
are right, left, and down without plotting. No other plotting vectors are recognized 
in section 3. 

Most of the time you will find that section 3 goes unused. This does not mean 
you can forget about using it altogether, but in most cases you can. If section 3 of 
a shape definition byte is set to zero, Applesoft ignores the section, moves on to 
the next byte of the shape definition and interprets it for drawing. 

Plotting vectors equal to zero can mean two things. In section 3 of each shape 
definition, a zero plotting vector always means “по movement and no plotting." 
However, in Table 6-3, a zero vector means “move up without plotting." This 
ambiguity can cause problems in sections 1 and 2 of each shape definition byte, 
because under certain circumstances Applesoft igriores zero plotting vectors, and 
in others it performs upward movement without plotting. The rule here is to never 
.end a shape definition byte with a zero plotting vector if you intend the zero vec- 
tor to mean "move up without plotting." Applesoft's shape manipulation routines 
assume that if the most significant portion (section 3) or portions (sections 2 and 
3 together) are set to O, no drawing action takes place at all for those sections set 
to O. 

If all three sections of a shape definition byte are set to O, Applesoft interprets 
this as an “end of shape definition” signal. In fact, you must end each shape 
definition with a termination byte, set to O. Otherwise, Applesoft will draw past 
the end of your original shape, and will continue drawing until it encounters a O 
byte. 

You can use the “move up without plotting" vector as long as a different plot- 
ting vector comes after it in the same byte. For example, section 2 can be set to O 
(which is “move up without plotting") and if section 3 is set to O1, 10 or 11 (bin- 
ary), section 2 will be recognized as "move up without plotting." If section З is set 
to O and section 2 is set to O, no movement occurs and Applesoft looks to section 
1 of the next byte for the next valid plotting vector. 

Armed with this knowledge, you can now arrange the binary-coded plotting 
vectors for each segment of the shape into groups of two or three. In this way, 
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you transpose the three-bit plotting vector codes into eight-bit bytes which can 
be stored in memory. Plotting vectors for a square map into a shape definition as 
shown in Table 6-5. 

With the shape now mapped into binary-coded bytes, you can easily convert 
each byte to hexadecimal notation. Appendix J contains a binary-to-hexadecimal 
conversion table. Table 6-5 shows the hexadecimal encoding of the square. 

The shape definition is now complete. The next step is to create a series of 
pointers to this shape (and others — up to 255 shapes) which Applesoft uses as 
a directory. 


Assembling the Shape Table Directory 


The directory of a shape table is a series of bytes which describes how many 
shapes there are in the table, and also points to each shape definition in the table. 
The first byte of the directory contains the total number of shapes in the table. 
This number ranges from O to 255 ($FF). The second byte is unused and should 
be set to zero. 

The remaining bytes in the directory contain pointers to each shape definition 
you have in the table. Each pointer is two bytes long and contains the offset 
(absolute distance in bytes) of the shape from the beginning of the directory. The 
low-order byte of the pointer precedes the high-order byte. For example, if the 
offset of a shape is ten bytes, you encode the pointer in hexadecimal as OA OO. In 
the case of our square, there is only the one shape to list in the directory, so the 
offset of shape 1 from the beginning of the directory is four bytes. Therefore, 04 
OO moves into this section of the directory. 


Byte 
0 01 -— — — Number of shapes in the table 
1 02 
2 04 
з 00 Offset of shape 1 from byte O 
4 258 (low-order byte first) 

Sh . ... 

5 37 \ ape definition 
6 00 -------- Shape ends with 00 


It is good practice to leave extra bytes at the end of a shape table directory to 
allow room for future shape table pointers. If you have no room at the end of the 
directory to allow for expansion, you will have to reorganize the entire shape table 
in order to insert a new shape pointer. Even though you may only need a directory 
which holds ten shapes, you should leave unused space at the end of the direc- 
tory; 20 extra bytes allow for another ten shape pointers which you can use later. 
When you want to add another shape to the table, place the new shape definition 
just after the last shape definition in the table, calculate the offset of the new 
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Displacement 


Number of shapes 
in table (O-$FF) 


Unused 
(set to zero) 


Offset of shape 1 
(low-order byte) 


Offset of shape 1 
(high-order byte) 


Shape Table Directory 


"11 This section's length 
2;+ 2 | Offset of shape / |l depends on the number 
(low-order byte) of shapes in the table 

(2 bytes per shape) 
" Offset of shape / 
ЕЗ (high-order byte) 
: Plotting vectors 
2i+ 4 Shape 1 


-— Always terminate shapes 
with 00 


Shape Tables 


Plotting vectors 
Shape / 


FIGURE 6-3. Shape Table Organization 
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TABLE 6-5. Coding a Shape Table (Square Shape) 


Hexadecimal 
Ses. ][Sec.2]S00.3|Sec.1]Sec.2]Se03| Codes 


None| | — | 00 | 100] 101 25 
None| | — | 00 |110 | 111 37 
None | None | Мопе| OO | 000 | 000 00 


shape from the beginning of the directory, place the new pointer immediately 
after the last shape pointer in the directory, and add 1 to byte O of the directory 
(which contains the number of shapes in the table). 

Figure 6-3 illustrates the way shape tables and their directory are organized in 
memory. 


Assembling Vectors by Computer 


The following program, written in Applesoft, assembles a shape definition for 
you. The program asks you to enter each plotting vector and whether or not to 
plot it. After entering the last vector, enter E for “end” and press Return. The pro- 
gram asks you to enter which vector, if any, to change. If you made any mistakes 
entering plotting vectors, you can correct them by entering the number of the 
plotting vector and then reentering the vector and whether or not to plot. 

If you have no further corrections to make, enter O as the response to VECTOR 
TO CHANGE (O=END). After a few seconds, the plotting vectors display іп hex- 
adecimal notation. Here is a listing of the program and its accompanying sample 
run: 

1 REM  sHiititit ibit 3E3ESE3E EHE EHE EIE тағанын 

2 REM : SHAPE CREATION PROGRAM % 

3 REM ж + 

4 КЕМ sti IE I I EEE 

10 DIM $S1(100).,V1(100) 

20150 

30 PRINT "CREATE SHAPE VECTORS" 

40 PRINT 

41 REM ENTER PLOT ACTIONS 

ЗО V = I: GOSUB 270 

58 REM CONTINUE ENTRY UNTIL МФ 

59 REM EGUALS TERMINAL VALUE "E" 

60 IF M$ < > "E" THEN S1(I) = M:I = I + 1: GOTO 50 

70 PRINT 

71 REM ALLOW CORRECTIONS 

80 INPUT "VECTOR TO CHANGE (O=END):"3¥V 

90 IF V > О THEN V = М – 1: GOSUB 270: S1(V) = M: GOTA ао 

99 REM PACK VECTORS INTO V1() ARRAY 

100 РОКУ = о TQ I 
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110 
120 
130 
140 
150 
160 
170 
178 
179 
180 
190 
200 
210 
220 
230 
240 
250 
260 
269 
270 
280 
290 
300 
310 
320 
330 
340 
350 
360 
370 


JRUN 


IF B = 2 AND S1(V) > О AND S1(V) < 4 THEN 140 
IF В < 2 AND (S1(V) > О OR S1(V) > 4) THEN 140 
В= 0:9 =H + 1 
V1(Q) = Vi(Q) + S1(V) > (8^ В) 
B=B+1 

IF В > 2 ТНЕМ В = 0:08 = 0 + 1 

NEXT V 


REM DISPLAY THE VECTORS AS 
REM HEXADECIMAL NUMBERS 
PRINT “BYTE”, "VECTOR" 

FOR У = о TO Q 

HX = V1(V) / 16 

L4 = V1(V) - HX * 16 


IF НХ > 10 THEN НХ = HA + 7 

IF L4 > 10 THEN LZ = 17 + 7 

PRINT V, CHR$ (HZ + 176): CHR$ (LX + 176) 
NEXT V 

END 


REM VECTOR INPUT SUBROUTINE 
PRINT "VECTOR "3V + 13%2"3 
INPUT "MOVE: U/D/L/R? "3 МФ 


M=0 
IF M$ = "R" THEN M = 1 
IF МФ = "D" THEN М = 2 
IF МФ = "L" THEN М = 3 
IF M$ = "E" THEN RETURN 


INPUT "PLOT (Y=YES,»N=NO)? “3Р% 

IF P$ = "Y" THEN M = M + 4: RETURN 
IF P$ = "N" THEN RETURN 

GOTO 340 


CREATE SHAPE VECTORS 


VECTOR 1:MOVE: U/D/L/R? 
PLOT (Y2YES;N-NO)? N 
VECTOR 2:MOVE: U/D/L/R? 
PLOT (Y=YES,N=NO)? М 
VECTOR 3:MOVE: U/D/L/R? 
PLOT (Y=YES,N=NQ)? Y 
VECTOR 4:MOVE: U/D/L/R? 
PLOT (Y=YES,N=NO)? Y 
VECTOR S:MOVE: U/D/L/R? 
PLOT (Y=YES,N=NO)? N 
VECTOR 6: MOVE: U/D/L/R? 
PLOT (YzYES,N-NO)? Y 
VECTOR 7:MOVE: U/D/L/R? 
PLOT (Y=YES,N=NQ)? Y 
VECTOR 8:MOVE: U/D/L/R? 
PLOT (Y=YES,N=NQ)? Y 
VECTOR 9:MOVE: U/D/L/R? 


ос c c c F г o ug 


PLOT (Y=YES,N=NQ)? М 
VECTOR 10:MOVE: U/D/L/R? R 
PLOT (Y=YES,N=NO0)? Y 
VECTOR 11:MOVE: U/D/L/R? R 
PLOT (Y=YES,N=NQ)? Y 
VECTOR 12:MOVE: U/D/L/R? R 
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PLOT (YzYES,NzNQ)? Y 
VECTOR 13:MOVE: U/D/L/R? D 
PLOT (Y=YES,N=NO)? М 
VECTOR 14:MOVE: LI/D/L/R? D 
PLOT (YsYES,N-NO)? Y 
VECTOR 15:MOVE: U/D/L/R? D 
PLOT (Ү=ҮЕЅ, №МО) ? Y 
VECTOR 16: МОМЕ: U/D/L/R? Ù 
PLOT (Ү=ҮЕЅ,№МС) ? Y 
VECTOR 17: МОМЕ: U/D/L/R? L 
PLOT (Y=YES,N=NQ)? М 
VECTOR 123: MOVE: LI/D/L/R? L 
PLOT (YsYES;NzNDO)? Y 
VECTOR 19:MOVE: U/D/L/R? E 


VECTOR TO CHANGE (ОзЕМП):О 


BYTE VECTOR 
о 12 
1 ЗҒ 
2 20 
3 64 
4 20 
3 15 
e 36 
7 1E 
е 07 
9 00 
J 


ENTERING THE SHAPE TABLE 


Before you can display any shapes which you code, you have to enter them into 
the computer's memory. In order to do this, you will need to determine what area 
of memory the shape table will reside in. The easiest way to allow for this space is 
to reset the HIMEM: pointer to a value just below the starting address of DOS, or 
just before the high-resolution graphics page you want to use. You must reset 
HIMEM: before you execute any Applesoft statements that use strings. If you use 
disk-based Applesoft, you will need at least 36K of memory (although 48K is bet- 
ter) to allow for the Applesoft interpreter and DOS. Addresses 115 and 116 ($73 
and $74) contain the latest HIMEM: setting for Applesoft, stored low-order byte 
first. To calculate the new HIMEM: value which allows for the shape table, use the 
following statement: 


PRINT PEEK(116) «256 + PEEK(115) – X 


This statement computes the HIMEM: value you should set, based on the 
parameter X which serves as the length of the shape table, including directory. 
Using this statement, replace X with the length of the shape table. Set HIMEM: to 
the computed value before entering the shape table into memory. This will protect 
the shape table from being overwritten by Applesoft. 
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As an alternative, you can place your shape table in memory between locations 
768 and 975 ($300 and $3CF) inclusive. Be sure the shape table does not con- 
flict with any machine language subroutines that you or your Applesoft program 
might put there. 

You can use POKE statements to place the shape table in memory. For exam- 
ple, the following series of POKE statements puts the shape table for our square in 
memory starting at location 768: 


JPOKE 768,01 
JPOKE 769,00 
JPOKE 770.04 
JPOKE 771,00 
1РОКЕ 772,37 
JPOKE 773» 35 
JPOKE 774,00 


You сап also enter a shape table from the Monitor. Use the statement CALL 
—151 to switch over to the Monitor. Then enter the hexadecimal memory address 
where the shape table will start, follow that with a colon, then enter the first byte 
of the shape table directory, enter a blank space, then enter the next directory 
byte followed by another space, and so on. Press Return. Now enter another 
colon followed by each hexadecimal byte of the first shape table (separate the 
bytes with spaces), and press Return. Repeat this last step for each shape in the 
directory. You can review your work by typing the hexadecimal starting memory 
address, a period, and the hexadecimal ending address of the shape table, then 
pressing Нетиям. For more information on how to use the Monitor, see Chapter 7. 
This is how you would enter the shape table for our square: 


JCALL -151 

% Monitor prompt 

i6000:01 00 04 ОО Enter the shape table directory 
#520 ЗЕ OO Enter shape 1 

36000. 60046 Check entries by displaying memory 


4000- 01 00 O4 00 2C ЗЕ ОО 
+ 


The shape table is now in memory. The first entry starts with the beginning 
address of the shape table (in this case, $6000). The colon (:) tells the Monitor to 
place the series of hexadecimal digits into memory. Immediately after the colon 
comes the shape table directory: O1 (the number of shapes in the table), OO (the 
second byte is unused), O4 and OO (the offset of shape 1 from the beginning of 
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the directory — the low-order byte comes first). The next line starts with a colon; 
no starting address is necessary if you set it in a previous entry. The Monitor will 
place the next series of hexadecimal digits immediately following the first series 
entered. 

The last line tells the Monitor to display memory addresses $6000 through 
$6006. The format for this command is: starting address, followed by a period 
(which telis the Monitor to display memory), followed by the last address to dis- 
play. Carefully check these entries for accuracy every time you use the Monitor to 
enter shape tables. 


Saving the Shape Table on Tape or Disk 


If you have invested a lot of time putting together shape tables, it certainly would 
be a good idea to save your work on magnetic media rather than lose it when you 
turn the Apple 1 off. You can use a cassette or disk to save a shape table; disk is 
preferable by far because it records and retrieves data much more quickly than 
tape. 

Applesoft has a command called SHLOAD which works exclusively with tape. 
Before you can save the shape table on tape, you must calculate the length (in 
hexadecimal) of the table. Continuing with the square as our example, look at the 
number of bytes taken up by the shape table; the total length is 7 bytes. Using the 
Monitor, enter the length of the table as a two-byte hexadecimal number, starting 
at address O: 

+00:07 ОО 

As always with two-byte quantities entered in the Monitor, the low-order byte 
comes first. Rewind the tape to the beginning. Then start itin RECORD mode. You 
will use the Monitor to record the shape table length and the table itself. This is 
done in two write operations, both of which you can enter on the same line: 

#0. IW 6000. 6006W 

The first write command places the two-byte shape table length you entered (at 
memory locations О and 1 above) on the tape. The second write operation places 
the seven bytes of the shape table, from address $6000 to $6006, on the tape. 
The two write operations take just over 20 seconds. The speaker beeps twice 
during the recording process. After the second beep, stop the recorder. The shape 
table is now on tape for you to use later. Use your actual shape table length, start- 
ing location, and ending location in place of the examples. 

To use the disk to save shape tables, get into Applesoft under DOS (from the 
Monitor, enter 3D0G). The command you use to save shapes is BSAVE. You need 
to know the starting address and length of the shape table you entered. To save 
the shape table starting at address $6000, the DOS command: 


BSAVE SQUARE, AS64000, L7 


creates the disk file SQUARE with filetype B for binary. The shape table is now 
saved on disk, ready for you to use at a later time. Use your actual shape table 
name, starting location, and length in place of the examples. 
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Loading Shape Tables 
from Tape or Disk 


If you saved a shape table on cassette, Applesoft will read the tape back into 
memory. First, rewind the tape to the beginning. Now type in: 


SHLOAD 


Press the PLAY button on your tape recorder. The Apple ІІ speaker beeps twice 
and then returns control of the computer to you. If some problem exists on the 
tape, you may see the cryptic message ERR on the display screen. If so, try read- 
ing the tape back in again, or, if the error persists, check the volume setting on the 
cassette recorder, as described in Chapter 2. SHLOAD automatically sets HIMEM: 
to the current HIMEM: value minus the length of the shape table in bytes. Make 
sure that the HIMEM: setting you have is correct. 

If you recorded the shape table on diskette, set HIMEM: before trying to read 
the table into memory. The following command reads the shape table in from 
iu BLOAD SQUARE 

DOS remembers what address you saved from ($6000 in our example) and 
will put the shape table there automatically. If you want to read the table in start- 
ing at a different address, say $3000, enter: 

BLOAD SQUARE; АФЗООО 

Here again, use the actual name and optional starting address in place of the 
example. 

After you BLOAD the shape table, you need to place the address of the shape 
table in addresses 232 and 233 ($Е8 and $E9). Applesoft uses these locations to 
point to the shape table in memory (SHLOAD sets this address pointer automat- 
ically). Enter the Monitor and set the address ($6000 as an example): 

ES:00 06 


Alternatively, you can use POKE statements to place the starting address of 
your shape table in locations 232 and 233. Remember that with POKE you must 
use decimal values. 

You are now ready to use the shape table in an Applesoft program. 


SHAPE DRAWING COMMANDS 
————— 


Applesoft has four shape manipulation statements which draw, erase and change 
the orientation of shapes: 

DRAW, which displays the shape on the Apple І! display screen. 

XDRAW, which can erase shapes drawn. 

ROT, which rotates the shape on the X and Y axes. 

SCALE, which alters the size of the shape drawn. 


The shape manipulation commands use the currently selected high-resolution 
graphics page (using HGR or HGR2) and color (using HCOLOR). 
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The SCALE Command 


As a programmed or immediate mode statement, you should always set SCALE 
before drawing a shape for the first time in a program. 

SCALE=1 
sets the scaling to draw one point for each plotting vector. If SCALE=5, the Apple 
ll will draw 5 positions for each single plotting vector. You can set SCALE as high 
as 255 (255 points plotted for each vector). The maximum scale setting is 
SCALE=0, which plots 256 points for each single plotting vector. 


The DRAW Command 


DRAW plots the shape (numbered from 1 to 255) from the shape table, in the last 
color chosen, at the scale and rotation value last set. This statement: 


DRAW 1 АТ 140,96 
plots the first shape definition in the shape table starting at the 141st column and 
97th row of the high-resolution display. Drawing originates at the column and row 
coordinates given in the statement. A second option of the DRAW statement uses 
an implied starting location. 
DRAW 11 
This statement draws the eleventh shape in the table at the point last plotted 
by the most recent HPLOT or DRAW statement executed. In case the coordinates 
were not set before, Applesoft defaults to zero coordinate values. 
IMPORTANT: Applesoft assumes that the shape table is properly located in 
memory. Before you execute a DRAW statement, make sure the shape table is in 
memory and that addresses 232 and 233 ($E8 and %Е9) point to the beginning of 
the shape table. If you specify a shape number greater than the number of shapes 
actually in the table, or if the DRAW statement uses row or column coordinates 
which are not valid, drawing does not occur; instead, the error message ?ILLEGAL 
QUANTITY ERROR displays on the screen. 


The XDRAW Command 


This statement allows you to erase a shape without erasing any high-resolution 
background graphics. Here is an example: 


XDRAW 8 AT 90,96 


This statement is syntactically identical to DRAW; the plotting coordinates сап 
be explicit as shown above or implicit as shown in the last DRAW statement 
example. XDRAW checks the color of the plotting coordinates and draws a shape 
in the complement of the color found. In the example above, XDRAW occurs at 
the 91st row and 97th column on the screen. Table 6-6 lists the complements of 
high-resolution colors. 

If the coordinates, rotation, and scale are the same as those of a shape already 
on the screen, XDRAW erases the shape, leaving all surrounding graphics intact. 
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TABLE 6-6. Draw Colors 


[if coloris — [XDRAW Color ts 


The ROT Command 


ROT rotates the shape about the center of the screen (on the X and Y axes). The 


statement: 
ROT=16 


sets the angle of shape rotation to 90 degrees clockwise. The values for ROT 
range from O to 255, although there are only 64 possible rotation settings, from O 
to 63. Figure 6-4 shows the changes in axis orientation based on ROT values. 

When SCALE is set to 1, ROT only rotates shapes in 90 degree increments, 
which means that only four meaningful rotations can be had: О-О degrees, 
16-90 degrees, 32-180 degrees, and 48-270 degrees. Applesoft rounds the 
rotation value you set to the next lowest ROT increment. All 64 rotational posi- 
tions are available if SCALE is set to 5 or greater. 


Using Shapes in a Program 


The following program listing uses shapes and should serve as a good example of 
how to use them in a program: 


1 LOMEM: 24400 

го HGR2 

SO REM SET SHAPE TABLE START ADDRESS 
40 POKE 232,0 

70 PORE 223.94 

78 REM USE ALL COLORS IN TURN 

76 FOR H= 1 TO 7 

79 REM INCREMENT ROTATION FACTOR 
ео FOR I = 1 ТО 80 

Sz  HCOLOR- H 

О КОТ= I 

92 IF I < 50 THEN SCALE= I 

105 DRAW 1 AT 140,96 

106 RüT- I + 32 

110 ПКАМ 1 АТ 140,96 

130 NEXT I 

140 NEXT H 

150 б650Тй0 76 


Working with high-resolution shapes is especially useful in game programs. 
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ROT - 10 


ROT - 16 


ROT - 24 


FIGURE 6-4. Shape Rotation 


You can build a library of shapes without having to heavily document them as you 
would HPLOT statements. Shapes cut down on memory consumption. Fewer 
calculations are necessary to manipulate the size and orientation of the high- 
resolution objects you create, and the calculations themselves are simple when 
compared to a series of HPLOT statements designed to display a shape. If you had 
some difficulty getting through this section on high-resolution shapes, it is proba- 
bly because you didn't try constructing shapes of your own. This is fairly complex 
material because so many steps are necessary to make even a single shape 
appear on the screen. If you use the program presented earlier which automat- 
ically encodes shapes, you will save some drudgery. 


APPLE 11 SOUND 


After the previous sections in this chapter it may be a relief as well as an 
annoyance to discuss programming the Apple I! onboard speaker. It is a relief 
because driving the speaker is really very simple. It can be an annoyance because 
you cannot control what the speaker does with BASIC statements. You have to 
define every sound the Apple li speaker makes in thorough detail. In essence, all 
you can do in programming the speaker is to make it emit a single click. The trick 
to making sounds with this speaker is to vary the frequency of these clicks, thus 
creating sounds of differing pitch. This section explains how to operate the 
speaker, and includes a program which creates a series of sounds. 


Chapter 6: GRAPHICS AND SOUND 225 


OPERATING THE SPEAKER 


The Apple ll uses memory location —16336, also known as 49200 and $CO30, 
as a toggle switch, much the same as the graphics switches discussed earlier in 
this chapter. Any time you access this location, a click eminates from the Apple Il 
speaker. In BASIC, you can operate the speaker by using the statement: 


A=PEEK (49200) 
A-PEEK(-16336) 


Using a BASIC program to drive the speaker (shown in the short example below) 
is easy, but the speaker will only generate lower frequencies. This is because 
BASIC is comparatively slow. In Integer BASIC, the highest frequency possible is 
about 256 Hz (cycles per second), and in Applesoft, the highest frequency is 
around 72 Hz. The only way to generate sounds of any higher frequency is to use 
a machine language subroutine to drive the speaker. 
9 REM CLICK THE SPEAKER 
10 A= PEEK (-16336) 
20 GOTO 10 


The Machine Language 
Sound Subroutine 


Applesoft and Integer BASIC allow room in memory between locations 768 and 
975 ($300 and $3CF) for machine language subroutines and shape tables with- 
out having to change LOMEM: settings. (DOS uses this area, eliminating all pre- 
vious contents, when you boot a DOS master diskette.) 

If you have not covered assembly language and machine language yet, you can 
still incorporate the following subroutine into Integer BASIC or Applesoft pro- 
grams by keying in a series of hexadecimal numbers. To place the subroutine into 
memory, get into the Monitor by entering the command CALL —151 or by press- 
ing RESET (/mportant : if you have DOS, make sure you boot it before entering the 
Monitor). Next, enter the machine language subroutine as shown below: 


2CALL -151 
%Е6666 


!302:LDY 301 


0302- АС 01 ОЗ LDY. $0301 Computer displays shaded 


! LDX 301 lines over your entries 
0305- AE 01 03 | LDX · $0301 

! LDA #4 

O308- А9 04 LDA #%04- 

! JSR FCAS 


ОЗОА- 20 А8 ҒС JSR  $FCAS 
! LDA СОЗО 
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озор- Ар зо со 
! INX 

0310- Ев 

! BNE 310 

0311- po FD 

! DEY 

0313- 88 

! BNE 305 

0314- DO EF 

! DEC ЗОО 

0316- СЕ 00 ОЗ 
! BNE 302 

0319- DO E7 

! RTS 

O31B- 60 


LDA 


INX 


BNE 


ПЕҮ 


ВМЕ 


ПЕС 


BNE 


RTS 


%СОЗО 


%0310 


%0305 


$0300 


$0302 
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This subroutine uses addresses $300 and $301 for data storage; addresses 
$302 through $31B hold the routine itself. Once you have entered the sub- 


routine, check it for correctness as follows: 


!$FF696 
#302L 


O302- 
0305- 
0308- 
0320A- 
030D- 
0310- 
0311- 
0313- 
0314- 
0316- 
0319- 
O31 B- 
031C- 
O31F- 
оз20-- 
0321- 
0322- 
0323- 
0224- 
0326- 


% --——-CraL-B into BASIC here 


ac oi 
AE 01 
a9 04 
20 AS 
АП 30 


Do FD 
Do EF 
СЕ 00 
ПО E7 


20 20 


10 38 


70 


LDY 
LDX 
LDA 
JSR 
LDA 
INX 
BNE 
DEY 
BNE 
DEC 
BNE 
RTS 
JSR 
РНР 
CLC 
CLD 
DEY 
PHP 
ШҮ 
BPL 


$0301 
$0301 
#$04 

ФҒСАЗ 
ФСОЗО 


$0310 


$0305 
$0300 
$0302 


$7020 


#$A0 
$0360 


If you have DOS on your Apple ll, you can save this subroutine on a disk with the 


BASIC command BSAVE: 


BSAVE SOUND, А%302, 26 
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This creates a binary file entitled SOUND; you can load this subroutine at a later 
time. If you have a cassette, record the routine by entering the following Monitor 
command: 

#302. 329W 


The subroutine is saved on tape for reading in at a future time. 


The BASIC Interface 


You will need a BASIC subroutine which talks to the machine language sub- 
routine. Enter the following listing in Applesoft or Integer BASIC: 


3200 REM SPEAKER DRIVER 

3210 POKE 768,D 

2220 POKE 769-Ғ 

3230 CALL 770 

3240 RETURN 
With this subroutine working in conjunction with the machine language routine, a 
BASIC program can generate sounds by setting two variables: F (for frequency) 
can range from 1 to 255, with 255 as the highest pitch, and D (duration), also 
ranging in value from 1 to 255, with 255 the longest duration possible. As an 
example, enter the following BASIC program after entering the subroutine listed 
above: 

10 FOR I = 1 TO 254 

20F = 1 

30 D= I 

40 GOSUB 3200 

SO NEXT I 

60 END 


When you run the program, listen to the duration of each note. On the low-fre- 
quency and high-frequency ends of the scale, sounds are shorter than those in 
mid-frequency. This problem is inevitable because the machine language 
subroutine uses instructions rather than elapsed time to change the frequency of 
each note. Since there is no real-time clock on the Apple Il, this approach is 
necessary. By setting longer duration values for very high and very low notes, you 
can compensate for this inequality. 


A More Elaborate Sound Program 


The program listed below uses the sound generation subroutines detailed earlier 
to create a series of sounds which you can listen back to, change, and finally print 
out for use in other BASIC progams. When you run the progam, you will see the 
prompt (ENTER, (L)ISTEN, (P)RINT? The first action is to enter some tones; enter 
E and press RETURN. 

Now the prompt TONE О: FREQUENCY, DURATION? appears. Enter two num- 
bers separated by a comma. The first is the frequency and the second is the dura- 
tion. Both numbers must be between 1 and 255. When you press Return after 
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entering the frequency and duration of the tone, the Apple il speaker emits the 
tone. This process repeats for a series of tones (up to 100). After the last tone you 
enter, input a O tone and O duration to complete entry. 

After you enter all the tones, the prompt WHICH NOTE TO CHANGE? appears. 
If you want to change any tones entered, input the number of the tone you want 
to reenter; otherwise, enter O. 

The prompt (ENTER, (L)ISTEN, (P)RINT? appears again when you finish mak- 
ing changes; now enter L and press Return. The Apple Il now repeats the entire 
series of tones you entered. When the last note plays, the prompt message 
appears again. Enter P to display or print the frequency and duration values of 
each tone. 

The program listing below can easily be modified to allow for saving the tone 
values on cassette or disk. Then other programs can retrieve the tone values and, 
using the sound generation subroutines, can play music or just emit random 
noises. 

10 REM SOUND GENERATOR PROGRAM 

19 REM ARRAY REMEBERS ENTERED TONES 

20 DIM 4(100,2) 

29 КЕМ CLEAR DISPLAY 

30 CALL - 936 

40 INPUT "(Е) МТЕК, (1) І5ТЕМ, (Р) КІМТ?" АФ 
SO IF A$ = "L" THEN 1000 

60 IF A$ = "P" THEN 1200 

SO IF A$ < > "E" THEN 30 

81 КЕМ ENTER EACH TONE 


90 PRINT 
1001-20 
1085 M= I 


110 GOSUB 3000 

119 REM END OF TONE ENTRY? 

120 IF F = О AND D = О THEN I = I - 1: GOTO 200 
129 REM  NO--REMEMBER TONE 

130 А(1.1) = Р:А(1,2) = D 

140 I= I * 1 

150 60Т0 105 

200 REM CHANGE АМҮ ITEMS HERE 

205 PRINT "WHICH NOTE TO CHANGE (O-";Is")"; 
206  INPUT E 

208 IF E = О THEN ЗО 

210 IF E < 1 OR E > I THEN 210 

220 M = E: GOSUB 3000 

230 A(E;1) = Р:А(Е, 2) = D: GOTO 205 
1000 REM LISTEN TO THE NOTES SO FAR 
1010 FOR K-20 TOI 

1020 F = A(K,1):D = А(К, 2): GOSUB 3200 
1030 NEXT K 

1040 GOTO 30 

1200 REM PRINT OUT THE NOTES 

1210 PRINT "NOTE#", "FREQ", "DURATION" 
1220 FOR K = 0 TO I 

1230 PRINT К,А‹(К,1),АСК, 2) 

1240 NEXT K 


Chapter 6: GRAPHICS AND SOUND 229 


1250 PRINT 

1260 GOTO 30 

3000 PRINT "TONE "Мз 

3010 INPUT " ENTER FREQUENCY, DURATION"; Р, 0 
3015 IF F = О AND D = О THEN RETURN 

3020 IF (F < О OR Р > 255) OR (D < 1 OR D > 255) THEN 3010 
3030 GOSUB 3200 

3040 RETURN 

3200 REM SPEAKER DRIVER 

3210 FOKE 768,0 

3220 POKE 769,Ғ 

5230 CALL 770 

3240 RETURN 


7 


Machine Language Monitor 


Residing permanently in the Apple Il read-only memory (ROM) is a control pro- 
gram called the Monitor. This chapter describes the Monitor's features and uses 
and shows how you can use it in conjunction with BASIC programs you write. The 
Monitor is written in machine language; it serves as a link between BASIC (and 
other languages which the Apple ІІ computer supports) and the various low-level 
functions which the machine performs, such as printing a character, plotting a 
line, and so forth. 

You can also use the Monitor via keyboard commands. Some reasons for doing 
this would be to create graphics shape tables (described in Chapter 6), to examine 
memory to isolate hardware problems, or to program in assembly language. Most 
of the time you will find no pressing need to use it, but the Monitor has some 
functions which you may find handy at some time. 

After describing the Monitor and its facilities, this chapter explains how to use 
the Mini-Assembler. This chapter does not teach you assembly language pro- 
gramming; Appendix K lists several books which do. You will learn how to inte- 
grate your assembly language program with a BASIC program, and how to use 
the Mini-Assembler to write, test, and debug it. 


ACCESSING THE MONITOR 


There are two versions of the Monitor: the standard version and the Autostart 
version. If your Apple ІІ has a standard Monitor, simply turning on the computer 
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will place you in the Monitor. In this situation you will see a screen full of random 
characters, with an asterisk (*) at the bottom lefthand corner of the screen and a 
blinking cursor directly to the right of the asterisk. The asterisk is the Monitor 
prompt character. 

If your Apple ІІ has an Autostart Monitor (either as an add-on feature or as 
standard equipment in an Apple ІІ Plus), you will have to use either Integer BASIC 
or Applesoft to access the monitor. When you see a BASIC prompt (either > for 
Integer BASIC, or ] for Applesoft), type in the following command: 


CALL -151 


This statement is actually a subroutine call to hexadecimal address FF69, but 
BASIC will not recognize hexadecimal numbers, so you must use the decimal 
equivalent of FF69 in this command. Once you key this statement in, the asterisk 
prompt, followed by the cursor, appears. At this point you are in the Monitor. 


LEAVING THE MONITOR 


There are a few ways in which you can exit the Monitor and return to BASIC; they 
largely depend on what you want to do when you leave it. To preserve program 
statements and variables used in the BASIC program, exit the Monitor by pressing 
CrRL-C and then pressing Return. After pressing Return, the prompt for BASIC 
returns. At this point, you can print the values of variables and list the program (if 
one happens to be in memory at the time). 

To illustrate, let's say that you put a value in a given memory location via the 
POKE statement and you want to verify the POKE. Of course, you could use PEEK 
to do the same thing, but the Monitor allows you far more access to the Apple Il 
memory than PEEK and POKE ever will. The Integer BASIC example below shows 
how using CrRL-C preserves the BASIC program and variables when leaving the 
Monitor: 310 àz123 

219 REM MOVE CURSOR TO 13TH COLUMN 
220 POKE 36,12 
230 PRINT A 


240 END 
>RUN 


УАШ -151 
3t -—— Press Crai-C, then Return 


ЭРКІМТ А 
123 
2LIST 
^. 10 Ағ123 

19 REM MOVE CURSOR TO 13TH COLUMN 

20 РОКЕ 36.12 

30 РКІМТ А 

40 END 


bv 
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If you want to leave the Monitor and clear out the current BASIC program and 
variables stored in memory, press CrRL-B and Return. This entry will return you to 
BASIC, but any program statements or variables which may have been in memory 
will be erased. Try the example above, substituting CrRL-B for CrnL.-C. After 
returning to BASIC from the Monitor, you will find that no value exists for А%, and 
that you cannot list the program. 

Crat-C works fine with Integer BASIC and firmware Applesoft. It does not 
work with cassette-based or disk-based Applesoft. 

With disk-based or cassette-based Applesoft you may use Crrt-B to exit the 
Monitor. In this case you will return to Integer BASIC, and all your Applesoft pro- 
gram and variables will be erased. There is a way to return to Applesoft with your 
program and variables intact. 

To return to disk-based Applesoft from the Monitor, type this command: 

#3D0G 
To return to cassette-based Applesoft from the Monitor, type this command: 
#0G 


3DOG and OG are two instances of the Monitor's branch instruction (analogous 
to the GOTO instruction in BASIC). More on this later. 
IMPORTANT: Use the command OG only with cassette-based Applesoft. 


FUNCTIONS OF THE MONITOR 


The Monitor performs a limited number of tasks, but each one is fairly powerful 
considering how small the Monitor program actually is. You can examine memory 
locations or the microprocessor registers, dump the contents of memory to the 
screen or to another output device such as a printer, and change memory or 
registers. Other functions include moving blocks of data from one address to 
another and comparing blocks of memory to each other. Still more miscellaneous 
functions appear in this chapter. 


EXAMINING MEMORY 


There are three methods in the Monitor of looking at the contents of memory 
locations: single-address, word, and block modes. A single address refers to a 
one-byte memory location. A word is an eight-byte segment of memory, begin- 
ning with an address divisible by eight. A block is a convenient means of looking 
at a range of addresses, starting at one address and ending at another address 
higher in memory. 


Examining Single Addresses 


When you see the Monitor prompt and you want to look at a single memory loca- 
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tion, just type in the hexadecimal address of the location you want to see followed 
by the Retuan key, as in this example: 


*FF67 

The Monitor responds by displaying the contents of that location: 
FF49- AY 
3t 


When you enter an address, the Monitor retains it for future use as a pointer. 
Therefore, if you enter FF69 (or any other hexadecimal address), the Monitor will 
remember that location, using it as a reference for further memory examination 
until you change the address. To change the pointer which the Monitor uses, 
simply key in a new address. For example, type: 


#300F 


and the Monitor resets the pointer in addition to displaying the contents of 
address 300F. 


Examining Words of Memory 


Let’s say you examined the single address FF69, as in the example above, and you 
want to look at the next higher locations in memory. The monitor will continue 
examining memory if you press Return, as shown below: 


HFFA? 


FF49- А 

+ «———— Press RETURN 

AA 88 33 20 67 FD 
E, 


FF70- 20 C7 FF 20 А7 FF 84 34 
3t ~——— Press Return again 
The first time you press the Return key in this example, six bytes of memory 

display on the screen. These are the contents of locations FF6A through FF6F. 
The second time you press Return an entire eight-byte word displays, but first the 
starting address of the word is shown (FF70) to remind you what the starting byte 
of this word is. All words start at memory locations which are divisible by eight, 
which is why an address did not print when you pressed Return the first time. The 
first Return merely finished off the block you had started earlier with the single- 
address examination. 


Examining Blocks of Memory 


You can examine a large block of memory (usually more than eight bytes) in block 
mode. Enter the starting hexadecimal address, followed by a period, and finally 
the ending hexadecimal address. For example: 

#F&00. РЕЗЕ 


Chapter 7: MACHINE LANGUAGE MONITOR 235 


The Monitor responds with the contents of the requested memory locations: 


F800- 4A 08 20 47 F8 28 AY OF 
F808- 90 02 69 EO 85 2E Ві 26 
F810- 45 30 25 2E 51 26 91 26 
F818- 60 20 OO F8 C4 2C BO 11 
F820- C8 20 OE ҒЗ 90 Fé 69 O1 
F828- 48 20 00 ҒЗ 63 СЗ 2D 90 
F8e30- FS 60 AO 2F ПО O2 АО 27 
F833- 84 2D Ао 27 AY OO 83 ЗО 
+ 


The starting address must be greater than or equal to the ending address in 
order for you to see more than one address. If the ending address is lower than the 
starting address, only the contents of the starting address displays. 

You can specify a range of addresses which exceeds the size of the Apple II 
screen. In this case, data scrolls off the top of the screen to make room for more 
at the bottom. You cannot cancel this display without pressing Reser. If your 
Apple ІІ contains the Autostart Monitor, you can temporarily halt the display by 
pressing CrRL-S. Using CrRL-S will stop output to the screen, but not to other out- 
put devices, such as a printer, giving you a chance to view the screen at your 
leisure. Press the space bar to restart the display. 

The block method of examination is typically called a dump. Once it finishes, 
the pointer which maintains the next location to examine updates itself so it is 
pointing to the byte after the ending address of the block examine. 

A shortened form of this command uses the pointer as the starting address of 
the block. You just enter a period followed by the ending address of the block. For 
instance, if you just looked at addresses F800 through F83F, as shown in the 
example above, you can continue examining a block beginning with F840 and 
ending with F880 by entering: 


+. F830 
which would result in the following output: 


F840- 20 28 F8 88 10 F6 60 48 
F848- 4А 29 ОЗ 09 04 85 27 68 
Е850- 29 18 90 O2 69 7F 85 26 
F858- OA OA OS 26 85 26 60 AS 
F860- 30 18 69 O3 29 OF 85 30 
F868- OA ОА OA OA OS 30 55 30 
F870- 60 4A 08 20 47 F8 Ві 26 
F873- 28 90 04 4A 4A 4A 4A 29 
F880- OF 

+ 


EXAMINING THE MICROPROCESSOR REGISTERS 


At some point you may want to inspect the registers in the microcomputer itself. 
This is done by typing Crat-E, followed by the Retuan key. The results look similar 


to this: 
А ? А-СП X-Bi1 Y=C3 P=BS S=FO 
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The values displayed are those stored in the Accumulator (A), Index Register X 
(X), Index Register Y (Y), the Program Counter (P), and the Stack Pointer (S). The 
values directly to the right of each equal sign are the latest values of the registers. 
However, they are not affected by operating the Monitor. In other words, the 
register contents are saved by the Monitor and remain unchanged until you either 
execute your own assembly language program or return to BASIC. 


ALTERING MEMORY 


Altering memory is more involved than examining it. You have to specify what 
address to alter as well as supply the new data which goes into that address. You 
can a|ter memory by single address (one byte at a time), or you can modify a 
series of consecutive locations in memory, entering new data for many addresses 
on one command line. 


Altering Single Addresses 


The first step in changing a single address is to set the Monitor's address pointer, 
which is the same pointer used in examining memory. Because both Monitor com- 
mands use the same pointer, you set the address to alter the same way you set 
the address to examine. Type in the hexadecimal address to alter, and then press 
Нетиям. For example: 41200 


sets the address pointer to 1200 hexadecimal. 
The Monitor responds with the contents of the memory location: 
1200- 73 
Notice that this entry produces the same result as a single-address examine 
command. The Monitor's response shows where the address pointer is set 
(1200), and also displays the current contents of the address (in this case, 73). 
The next step is to alter this address to a new value. To change memory at this 
address, first type a colon (:) followed by the two-digit hexadecimal number you 
want to place at the address you just set. For example: 
+: SF 
The colon indicates a memory alteration command to the Monitor. The 5F indi- 
cates the new data to place at address 1200. You can alter memory using one 
command line instead of two, as shown below: 
#1200: SF 


This command line has the same effect on changing address 1200 as the two 
separate lines shown above. The address pointer updates to 1200, and the Moni- 
tor places 5F in that address. The address pointer moves to the next highest 
memory location. So if you want to change address 1201 to 7F, for example, 
type: ж: УЕ 


and the Monitor automatically updates this address to hold 7F. Again, the address 
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pointer increments by 1 and you can alter address 1202 to some different value 
by continuing the process of entering data without explicitly entering the address. 


Altering More Memory 


The Monitor lets you change more than one memory location at a time, provided 
that the addresses you change follow each other consecutively in memory (for 
example, addresses 1200 to 1207 inclusive). This command starts the same way 
as the single-address method of altering memory. You first set the address 
pointer if necessary. Next, use the colon to indicate to the Monitor that this is a 
memory alteration command. Finally, enter the data you want at each consecutive 
location, sepárating each hexadecimal number with a space. 

For example, to place the quantities OO through 07 in addresses 1200 through 
1207, enter: жі200:00 01 O2 ОЗ 04 OS 06 07 

You can actually alter many more addresses than eight. If you set the pointer at 
the beginning of the command, you could enter as many as 83 values on one 
command line. If you do not set the pointer, you can enter up to 84 values. In 
either case, the command line would wrap around to encompass several display 
lines. This is impractical because the wraparound command line makes checking 
entries extremely difficult. Moreover, the only way to correct errors is to back- 
space to them, retyping the balance of the line after making the correction. But if 
you are inclined to enter so much data on one command line, the Monitor will 
allow you to do so. 


Checking Memory Alterations’ 


It is good practice to check memory alterations if you want the final product 
(whether a graphics shape table or a series of machine instructions) to be totally 
accurate. To do this you will have to use one of the three possible memory 
examine commands discussed earlier in this chapter. To begin checking the 
alterations you made, you once again have to reset the address pointer to where 
you first made alterations. 
Assuming you placed OO through 07 at addresses 1200 through 1207, as 
shown in the example above, reset the pointer to 1200: 
+1200 
The Monitor responds with: 
1200- OO 
+ 


By pressing Return you can see the remaining seven addresses which you 
changed: 


% 4«——— — Press Return 
O1 O2 O3 O4 OS O6 O7 
+ 


If you altered more than a few locations, keep pressing Return until you see the 


238 APPLE Il USER'S GUIDE 


last alterations you made. 
You can also use the block examine mode to check this area: 
#1200. 1207 


The Monitor responds with: 


1200- OO O1 O2 O3 O4 OS O6 07 
+ 


Correcting Mistakes 


If there are any mistakes in the addresses you altered, you can correct them 
individually without having to reenter all the data correctly. The simplest way to 
` do this is to note the address of the incorrect data and enter a single-address 
alteration for it. 

For instance, if you made a mistake entering numbers OO through 07 in the 
previous example, and the error appears at address 1204, enter: 

%1204:04 

to correct the error at this address. The next step is to look back at address 1204 
and make sure you got it right this time. Then finish checking over any other 
alterations to ensure that all of the data you entered is correct. 


ALTERING THE MICROPROCESSOR REGISTERS 


The process of altering the microprocessor registers is slightly different from 
altering memory, since the registers actually have no addresses. To alter the con- 
tents of the registers, you first have to examine them using the CrRL-E command. 
Immediately following a register examination command, you can change the con- 
tents of the registers by typing in a colon (signifying an alter operation to the 
Monitor), followed by one to five hexadecimal numbers. Separate the numbers 
with spaces. 

The first hexadecimal number will be the new value of the Accumulator, the 
second number will be the new value of Index Register X, the third number 
becomes the value of Index Register Y, the fourth number becomes the value of 
the Program Counter, and the fifth number is the new value of the Stack Pointer. 

You must enter values for all registers up to and including the last register in the 
series you intend to change. You may leave off values for any registers beyond 
that. 

As an example, say you want to change Index Register Y while leaving all other 
registers intact. First, examine the registers with CrRL-E. 


4t -———— Press Crat-E, then Return 
А-СП Х-Ві Ү-СЗ PzBS S-FO 
% 


(Note that the register contents you see here are just examples.) 
To change Index Register Y to hold the hexadecimal quantity 8A without 
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changing any other registers, type the existing values of the Accumulator and 
Index Register X, followed by the new value for Index Register Y. 
+: CD B1 СЗ SA 


To alter any register other than the Accumulator (A), you have to reenter the 
contents of all registers up to and including the one which you want to alter. 

You must press CrnL-E (then Return) to examine the registers, or the Monitor 
will assume you want to alter a memory address. Examining the registers tells the 
Monitor to switch from using the address pointer to a location to alter, and instead 
directs it to alter the registers themselves. 

To illustrate another register alteration, assume you want to change the Stack 
Pointer (its contents follow the S when examining the registers) to hold the quan- 
tity 4B. First, remember to examine the registers: 


Ф -<-----Ргесв Crat-E, then Return 


A=FF X=CD Ү=& 1 P=8A S=FO 
+ 
Now enter the current values, in order, for all other registers, and then the new 
value for the last one: 
я:ЕЕ CD 81 SA 4B 
Verify that the change is correct by using CrRL-E to examine the registers once 
again. 


SAVING AND RETRIEVING MEMORY 
WITH APPLE Il PERIPHERALS 


The Monitor allows you to use a cassette recorder to save the contents of a block 
of memory on magnetic tape. You will want to do this if you create high-resolu- 
tion graphics shapes (see Chapter 6), or if you write assembly language programs 
which you want to store. With the Apple Il Disk Operating System (DOS), you can 
store memory contents even more quickly and reliably, on disk. In order to save 
memory on disk you have to temporarily leave the Monitor, using the DOS 
through BASIC to save or retrieve memory. 


Saving Memory on Cassette Tape 


To save memory on tape, use the Monitor's memory write command. You have to 
supply the Monitor with the beginning and ending addresses of the memory 
which you want to save. The command to write memory to the tape begins with 
the starting address you want to save followed immediately by a period, the end- 
ing address of memory which you want to save, and finally the letter W. 
For example, the command: 
#2200. 2FFFW 

tells the Monitor to write the contents of memory, starting at hexadecimal address 
2000 and ending with address 2FFF, on the cassette recorder. 
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The memory write command does not check data it sends out the cassette 
port; it also does not (and cannot) check for the actual presence of an operating 
tape recorder connected to the cassette ports. You should do all you can to 
ensure that the tape you use is free from jamming, dropouts, and other problems 
which are inherent in using tape cassettes. 

When you enter the command to write memory, don't press Return until you 
put the cassette recorder in RECORD mode and the tape is visibly moving in the 
machine. If the cassette you are using is at the beginning of the tape, let it run for 
at least five seconds before pressing Return, to allow the nonmagnetic leader 
tape to pass through the recorder. 

When you press Return, the computer waits ten seconds before sending data. 
This allows the cassette recorder to erase any previous information (music, voice, 
or machine-readable data) on the tape. The computer sends a reference tone to 
the recorder during this time. The Monitor uses this tone later as a locking-on sig- 
nal in the memory read command (covered in the next section). 

When the memory write command finishes, the Apple ІІ speaker beeps once 
and the Monitor prompt returns. 

The memory write command enables you to record from one byte to 64 
kilobytes (65,536 bytes) on tape. The Monitor sends data through the cassette 
output port at an approximate rate of 210 characters per second (based on a 
16,384-byte move in 77.5 seconds, after the reference tone). After transmitting 
the last byte of data, the Monitor sends a checksum byte to the cassette recorder. 
The memory read command uses this checksum byte to test incoming data for 
validity. 


Retrieving Data from Cassette Tape 


The memory read command enables you to retrieve data from the cassette 
recorder and load it into memory. To perform the memory read command, enter 
the starting address (where data from the cassette tape should begin loading into 
memory) followed immediately by a period, the ending address (where the last 
byte of data read from cassette will go in memory), and lastly the letter R. 


For example, the command: 
#2000. 20FFR 


means read data from cassette tape into memory, starting at hexadecimal 
address 2000 and ending at 20FF. 

Unlike the write command, the memory read command forces the Monitor to 
wait until you press the PLAY button on the cassette recorder. The computer 
waits for the signal tone from the cassette recorder, and the Monitor will lock out 
the computer until it encounters the signal. Before you press PLAY on the cassette 
recorder, make sure you position the tape to where the reference tone begins. You 
can tell the difference between the reference tone and actual data on the tape by 
listening to it. Remove the connector from the earphone jack to listen to the tape 
using the cassette recorder speaker. The reference tone is a steady, medium- 


Chapter 7: MACHINE LANGUAGE MONITOR 241 


pitched hum. Actual data sounds like random noise or static. 

Be sure to adjust the cassette recorder playback volume before using the 
memory read command. The procedure for adjusting the volume is explained in 
Chapter 2. 


The memory read command expects to read in exactly as much memory as 
you saved using the memory write command. If you write 1024 bytes from 
memory onto tape and want to retrieve only the first 256 bytes which you 
recorded, the Monitor will transfer data but you will probably receive an error 
message. The same is true for reading more data into memory than was recorded 
on tape; an error message is a strong possibility. 


Error Conditions in the 
Memory Read Command 


The Monitor listens to the cassette recorder for at least 3.5 seconds before 
expecting data from the cassette input port. This allows the Monitor to lock on to 
the frequency of the reference tone. If the tape contains less than 3.5 seconds of 
this tone the Monitor will lose the beginning of the data transmission from the 
cassette, resulting in a checksum error. Furthermore, you will not be sure where 
on the tape the Monitor began reading data, because the Monitor always attempts 
to move data into memory from cassette — valid or not. In this case the Monitor 
error message occurs (a beep from the Apple ІІ speaker followed by the message 
ERR and the Monitor prompt). To correct the error, rewind the tape to the begin- 
ning of the tone. Press PLAY with the Apple ІІ cassette connector disconnected 
from the earphone jack and time the tone. If it is less than 3.5 seconds before you 
hear the data transmission, you have to write memory to the tape again. It is pro- 
bable in this case that you forgot to move past the nonmagnetic leader tape at the 
beginning of the cassette before recording. 

Reading more or less data into memory from cassette than was originally saved 
on the tape will probably cause an error message to display on the Apple Il’s 
screen. The last byte sent to the cassette recorder in the memory write command 
is a checksum byte. Its value depends on how much data was written as well as 
what data was written. When a memory read is not equal in length to the original 
memory write, the Monitor cannot predict which piece of incoming data will be 
the checksum byte. The Monitor assumes that the last byte it reads from cassette 
into memory (determined by the ending address in the memory read command) 
will be followed by a checksum byte. The Monitor performs its own internal 
checksum calculations on incoming data during the memory read operation and 
compares this with the checksum byte it reads in from cassette. If the two bytes 
do not agree, the Monitor displays its error message. It is possible for the 
checksums to agree by coincidence. As a general rule, you should only read in as 
much memory as you wrote to the cassette in the first place. This lets the Monitor 
perform meaningful error checking. Later in this chapter you will see how to verify 
a memory read operation using the Monitor. 
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Saving Memory on Disk 


With the Apple ІІ Disk Operating System, saving memory is much quicker and far 
more reliable than with cassettes. The rules for saving memory on disk are slightly 
different because you use BASIC rather than the Monitor to perform this function. 
Even so, this is a machine-level command which is superior to cassette com- 
mands included in the Monitor, and you should use it where possible. Before read- 
ing this section, you should be familiar with DOS (see Chapter 5). DOS must 
already be in memory before you begin (see Chapter 2). 

If you are in the Monitor, you need to leave it temporarily and get into BASIC 
under DOS with the CrRnL.-B or CrR.-C command if you have the Autostart Moni- 
tor, or the 3DOG command if you have the standard Monitor. 

Here is an example of the DOS command to save memory on disk: 


BSAVE SHPTABLE, AS3S000, L256, 56. рі, V201 


This command will create a DOS file on disk called SHPTABLE. The next 
parameter, A$3000, will save memory on disk starting with address 3000 hex- 
adecimal. The A stands for address. The third piece of information, L256, 
specifies the length (L) of the memory write, in this case the decimal number 256. 
The maximum length is 32767 decimal ($7FFF hexadecimal). BSAVE allows you 
to use hexadecimal or decimal numbers as address (A) and length (L) parameters. 
If you use hexadecimal constants in the BSAVE command, make sure to precede 
the constant with a dollar sign. 

The last three parameters in this sample statement (S6, D1, V201) are 
optional. They specify which disk to use. Use the S (slot) parameter only if you 
have more than one disk controller card and the disk drive you want to save 
memory on uses a controller card other than the one last used (usually slot 6, the 
standard disk drive slot). The D (drive number) parameter is useful but not necess- 
ary; specify the drive number only if it differs from the drive you accessed last. 
The optional V (volume number) parameter is the volume number stored on the 
directory of the disk you are saving memory on. If the volume number you specify 
in the BSAVE statement differs from the volume number on the disk you want to 
save memory on, an error message appears. 


Retrieving Memory from Disk 


As with BSAVE, you use DOS to retrieve data from disk and load it into memory. 
The BLOAD command does this. 
Here is an example of BLOAD: 


BLOAD SHPTABLE, А%3000 


This example loads the file named SHPTABLE from the disk currently in use and 
puts the data directly into memory, starting with address 3000 hexadecimal. This 
command statement also accepts a decimal address. The A (starting address) 
parameter is not necessary if the file contents start at the same location they were 
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saved from. You need only specify an address if it differs from the BSAVE starting 
address. The length parameter (L) is optional but not necessary. DOS checks the 
length of the disk file itself and terminates the memory read command automat- 
ically. The optional disk specification parameters used іп BSAVE (S, D, and V) can 
also be used in BLOAD to indicate a slot, drive, and volume number. 

Be careful not to use this command in areas of memory which may be 
occupied by DOS, the Applesoft interpreter, text or graphics pages, or BASIC 
variables. It is possible to clobber these areas of memory, losing data which you 
may have wanted to keep. 


MOVING AND COMPARING 
BLOCKS OF MEMORY 


If you read or write memory using tape or disk, the Monitor has two functions 
which may help you. The move function copies a block of memory into a different 
range of addresses. The compare function checks two blocks of memory against 
each other and reports any discrepancies between the two blocks. When used 
with the Monitor's memory read and memory write commands, these functions 
furnish you with added insurance that the files you write contain correct data. 


The Move Memory Command 


In order to move data from one address in memory to another, you have to supply 
the destination start address (where you want to move memory to), the source 
start address (where to move memory from), and the source end address (the last 
address you want moved). The format of this command is the destination start 
address followed by the less-than symbol ( «), the source start address, a period, 
the source end address, and the letter M (for move). As with other Monitor com- 
mands, all addresses are hexadecimal numbers. 
For example, the command: 


%1200<2000.2100М 


moves data to address 1200 hexadecimal (the destination start address) from the 
block starting at 2000 hexadecimal (the source start address) and ending with 
2100 (the source end address). The Monitor copies the contents of memory, 
from addresses 2000 through 2100 to addresses 1200 through 1300 in this 
example. Since the addresses are hexadecimal, the implied length of the move is 
257 bytes decimal, or 101 bytes hexadecimal. The original contents of addresses 
2000 through 2100 remain undisturbed. 

When you specify addresses in the move memory command, the source start 
address should be greater than or equal to the source end address. If the source 
end address is less than the source start address, the Monitor will only move one 
byte from the source start address to the destination start address and then will 
terminate the move memory operation. 


244 APPLE Il USER'S GUIDE 


Filling Memory 


The move memory command also fills memory. Filling is the process of moving 
one or more bytes of data repeatedly to consecutive addresses. Suppose you 
want to place zeros in a block of memory, starting with address 1DOO and ending 
with 1DFF. By creative use of the alter memory and move memory commands you 
can set a block of memory to a predefined set of values, or pattern. 
To begin, you might place zeros in the first byte of memory: 
+1000:00 


This is the first step of the fill memory procedure. The second step uses the 
move memory command to copy the contents of one (or more) bytes into an 
adjoining block of memory. 

Specify a destination start address which is one greater than the last byte of 
the pattern (in this example it would be 1DO1). Set the source start address to the 
beginning of the pattern (1000 in this case), and set the source end address to 
the last byte which you want filled (1DFF) minus the length of the pattern you 
want to fill memory with (1DFE). 

Continuing the example, the command: 

x1DO01«1LD00. 1DFEM 


fills locations 1001 through 1DFF with zeros (or more precisely, with the contents 
of location 1DOO). This procedure only works when the fill pattern exists at the 
beginning of the block you want to fill. Here's what happens. Since the destination 
start address comes one byte after the source address, the Monitor moves data at 
address 1DOO to 1D01 first, moving OO into this address. When the second byte 
is moved, the Monitor takes the contents of location 1DO1 and moves it into 
address 1002. This process continues until the contents of address 1DFE (set to 
OO in the last byte transferred) move into address 1DFF. By examining these loca- 
tions you can see that addresses 1DOO through 1DFF are indeed filled with zeros. 

You may want to fill memory with a pattern which is more than one byte long. 
For example, to move OO 5E 7F FF and fill memory from 1DOO through 1DFF with 
this four-byte pattern you need to alter four bytes of memory starting at address 
1000: 

#+1000:00 SE 7F FF 

The pattern is now in place. To fill memory up to 1DFF with this pattern, enter 

the command: 
:1DO4«1D00. 1DFBM 

Note that the destination start address occurs one byte after the end of the 
pattern, the source start address points to the beginning of the fill pattern and the 
source end address points to the last address to fill minus the length of the pat- 


tern: 1DFF 
—04 (Hexadecimal Arithmetic) 
1DFB 
Once again, if you try this example you can examine memory from 1DOO 
through 1DFF to verify that the pattern repeatedly occurs in this block. 
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The Verify Memory Command 


This Monitor command compares two blocks of memory against each other, not- 
ing differences between the first block and the second. You can use this com- 
mand in conjunction with the memory read and memory write commands which 
the Monitor and the Disk Operating System (DOS) support. If you save memory 
onto a peripheral device and want to be sure it was written correctly, you can use 
the verify memory command to do that too. 

The format for this command is nearly the same as for the move memory com- 
mand. Enter the destination start address (where to start comparing memory) 
followed immediately by the less-than sign («), the source start address (where 
to start comparing to the destination), a period, and the source end address 
(where the last byte of the verify memory operation will take place). The last item 
on the command line is the letter V, for verify. 

Here is an example: 


жз2По<о.СУ 


This instructs the Monitor to start comparing data at address 3200 against 
address O, and to continue the comparison until address 32DC is compared and 
verified against address OOOC. Notice that no leading zero digits are needed for 
addresses in a Monitor command line. 

If the Monitor encounters a byte in the source block which is not the same as 
its counterpart in the destination block, the source address displays with its stored 
value, along with the value it found at the same relative address in the destination 
block. 

For example, if you moved memory from addresses 0000 through OOOC to 
addresses 32DO through 32DC: 


#3200<0. CM 


and then displayed the source and destination blocks: 
#0.C 


O000- 4C ЗС D4 4C 3A DB 8C 8C 
0008- FF FF 4C 99 El 
#3200. 32DC 


32DO- 4C 3C D4 АС ЗА DB SC 8C 
3208- FF FF 4C 99 Е1 
+ 


you could visually check the move memory operation. If you alter address 32D8 
from its present value (FF) to 5A: 


#3208: SA 
and then enter the verify memory command: 
32DO«O. CV 


the Monitor will compare the source block against the destination block byte-by- 
byte until it compares data stored at 0008 against the value іп 3208. Since 
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address 32D8 was just altered, the Monitor displays a discrepancy: 

ооов-ҒЕ (5A) 

* 
meaning that the value at address 0008 in the source block does not agree with 
the same relative address (32D8) in the destination block. The Monitor first dis- 
plays the value it finds at the source address (0008, the contents of which are FF) 
and then displays in parentheses the value stored at the destination address 
where the discrepancy occurred (5A). 

The address in the destination block does not appear; the Monitor assumes 
that you can add numbers in base 16 easily to find the address of the discrepancy 
in the source block. One way to avoid calculating the address yourself is to switch 
source and destination blocks: 

#0<32D0. 32DCV 
which will produce: 

3208-ЗА (FF) 

+ 

This message shows that source address 3208 contains БА hexadecirnal, 
while its relative counterpart (address 0008 as seen above) contains FF. This 
method eliminates one calculation but it adds another; that is, you need to calcu- 
late a new source end address (32DC). 


Verifying Memory Stored 
on Apple Il Peripherals 


The verify memory command is especially useful if you save memory contents 
onto cassette tape or disk. By saving a portion of memory and then loading it back 
in at a different location, you can verify that memory was saved properly. The 
following example shows how to perform this procedure for assembly language 
programs, shape tables, and other information which you can store from memory 
to Apple Il peripherals. 

If you are using the cassette recorder to save memory onto tape, the first step 
is to enter the memory write command as shown in this example: 

#2000. 20FFW 


This command writes data from memory, starting at address 2000 and ending 
with address 2ОҒҒ, onto cassette tape. Don't forget to start the recorder іп 
RECORD mode before you press Return. Once the Apple ІІ speaker emits a beep 
to notify you that the memory write operation is finished, stop the cassette 
recorder and rewind the tape to where the reference tone begins. Assuming that 
memory from 2100 to 21FF is available, use the memory read command to load 
data from cassette to address 2100, ending with address 21FF: 

#2100. 21FFR 

Don't forget to start the recorder with the PLAY button. When the Apple Il 
speaker emits a beep, the memory read operation is complete. Now you can verify 
memory against what you saved on tape: 

:2000«2100.21FFV 
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The verify memory command compares memory, from 2000 to 20FF, to 
memory which was written to cassette and read back in starting at address 2100. 
If no discrepancies display, you can be sure that the memory write operation was 
successful. 

To verify memory saved on disk, the same general procedures apply. Before 
attempting to save or retrieve memory using the disk drives, the Disk Operating 
System has to be in memory as well. Here, the first step is to BSAVE the block of 
memory onto disk: 

ESAVE MEMDATA, А%2000.1-ФҒҒ 

Memory saved on disk, in the file named MEMDATA, can be read back in using 
BORD: BLOAD MEMDATA, A$2100 

Note that the address parameter in this statement is 256 bytes (decimal) 
higher in memory than the original block saved. When file MEMDATA is read in, 
the verify memory command compares the two blocks: 


CALL -151 


%2000<2100.21ҒҒУ 
If no discrepancies occur, you can be sure that memory was properly saved 
onto disk; otherwise, the Monitor will point out differences between the blocks in 
order for you to correct them. 


THE GO COMMAND 


The Monitor has a command which transfers control of the Apple Il to a program 
at an address you specify. Toward the beginning of this chapter, you saw how to 
leave the Monitor and go back to the disk-based Applesoft. The command: 
#3D0G 

instructs the Monitor to jump to address 3D0 in memory and execute the machine 
language instruction it finds there. The letter G at the end of the command line 
stands for GO. If you enter the command shown above and DOS is in memory, 
address 3D0 contains the first part of the assembly language instruction: 


JMP $9DB9 


When the Monitor transfers control to the instruction at address 3DO, the com- 
puter branches to address 9DB9, where the DOS routines begin. 

The general format for the GO command is the address to transfer control to, 
followed by the letter G. The address is optional; if none is entered, the Monitor 
uses its memory pointer as the assumed address. 


USING THE PRINTER 


If your Apple Il connects to a printer via the Serial Interface or Communications 
card, you can use the printer for output. To divert all output from the screen to a 
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printer, enter the slot number of the interface card which controls the printer, 
followed by CrRL-P and Return. Once you enter this command, all output normally 
displaying on the screen will be routed to the printer. To select the Apple ll screen 
as the console output device, use slot number О with the CrR.-P command. 

When using this command, be sure that the slot you select has an interface 
card in it. If no interface card exists at the slot you specify, the Apple Il will lock up. 
The only way to recover from this condition is to press Reser. 

The printer command works exactly the same way as the РВ: (slot number) 
command in BASIC. Both of these commands set the two-byte CSW switch 
(character output switch) at address 54 ($36). These two bytes contain an 
address which points to the character-output subroutine currently in use. By 
changing the slot with CrnL-P, you change the contents of the two-byte CSW 
Switch. 


THE KEYBOARD COMMAND 


This command directs the Monitor to accept input from a device other than the 
Apple Il keyboard. As with the printer command, you specify the slot number for 
the device. Follow the slot number with Crri-K, then press Return. To return con- 
trol to the Apple ІІ keyboard, enter a keyboard command with a slot number of 0. 

This command sets the KSW (keyboard input switch) at address 56 ($38) to 
a two-byte address derived from the slot number entered in the keyboard com- 
mand. 


SETTING DISPLAY MODES 


To view Monitor output on the screen in inverse video, enter the inverse video 
command, abbreviated as |. This will cause all data which the Apple І! displays to 
appear as black letters on a white background. However, any Monitor commands 
you enter will still display in normal, white-on-black video. 

To terminate inverse video, enter the normal video command, abbreviated as N. 
Neither of these commands needs any additional parameter other than the letter | 
or N. 


EIGHT-BIT BINARY ARITHMETIC 
USING THE MONITOR 


The monitor performs eight-bit binary addition and subtraction. The results of the 
arithmetic are also eight bits long. To perform addition, enter a hexadecimal 
addend followed by а plus sign (+) and a hexadecimal augend. If the result is 
greater than FF, the Monitor truncates the most significant digit and displays the 
low-order eight bits of the result, as shown in this example: 


#7F+8A 
=09 
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To perform subtraction, enter the minuend followed by a minus sign (-) and 
the subtrahend. As with addition, both numbers have to be hexadecimal. If the 
result is less than zero, the Monitor displays the ones complement result, as 
shown below: 

#OA-20 
zpD 


USER-DEFINABLE MONITOR COMMAND 


By entering CrRL-Y in response to a Monitor prompt, you invoke a special user- 
definable command. The Monitor automatically jumps to hexadecimal address 
3F8 when Ствні-Ү is entered. There is enough room at location 3F8 for one 
machine language jump instruction. If you have a special machine language pro- 
gram somewhere in memory, Crat-Y could initiate a jump to it via location 3F8. 

The example below shows how to set up Crat-Y to restart disk-based 
Applesoft without typing the familiar 3006 command. 

First, you need to know the format of a machine language jump instruction. It 
takes three bytes. The first byte is the instruction code, 4C. The next two bytes 
are the address to jump to, with a twist. You must specify the /ast byte of the 
address first (kind of like last name first). 

Here's a memory alteration command that sets up a jump instruction to 
address 3DO: xsFe:4c по o3 
Now try CrRL-Y. That certainly beats 3DOG! 

For another example, let's see how you would use Crat-Y to jump to the Mini- 
Assembler, which the next section covers in detail. If you enter the Monitor com- 


mand: #66666 
the Mini-Assembler prompt appears: 
[] 


The address where the Mini-Assembler starts, F666, can be used in a JMP 
instruction at address 3F8: 
'"SFS:JMP $F666 


O3F&- 4C 66 Fé JMF $F&66& -—-The Mini-Assembler 
} displays this line 
Although the Mini-Assembler is not discussed until the next section, the line 

above sets the address of this instruction to 3F8 hexadecimal, and the operand 
($F666) indicates a jump to the beginning of the Mini-Assembler program. To 
return to the Monitor, enter the command: 

'SFF69G 

+ 
The Monitor prompt reappears in the lower lefthand corner of the screen. After 
this point, if you press Crn.-Y the Mini-Assembler prompt appears. Setting the 
user-definable command to the Mini-Assembler saves keystrokes used in invok- 
ing it. Reset the user-definable command by placing a different jump instruction at 
address 3F8. 
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THE MINI-ASSEMBLER 


If you have the standard Apple Il (or the Integer BASIC card with the Apple II Plus), 
you have a program in ROM which spares the machine language programmer the 
torture of hand assembly. The Mini-Assembler resides with Integer BASIC in 
ROM. It is called mini because the programmer has to use literal addresses, rather 
than mnemonic labels, as operands in assembly language statements. Also, each 
line of code you enter is automatically and immediately assembled into machine 
language. The principal problem here is that you cannot insert or delete instruc- 
tions at will, as you can with a full-fledged assembler with a text editor. 

The principal advantage of the Mini-Assembler is the ability to enter machine 
instructions directly into the Apple 11, while still keeping the convenience of as- 
sembly language mnemonic instructions. 

The balance of this chapter describes the Mini-Assembler and tells how to use 
it. The chapter most definitely does not explain assembly language programming 
concepts. Nor does the chapter cover the 6502 instruction set which is the as- 
sembly language the Apple ІІ uses. 

So if you're already confused with this talk of assembly, operands, mnemonics, 
and so forth, stop right now. Learn assembly language programming techniques 
and the 6502 instruction set first. Then finish reading this chapter. 


ACCESSING THE MINI-ASSEMBLER 


The entry point address of the Mini-Assembler program is F666 hexadecimal. To 
begin from the Monitor, enter the command: 
*F6666 
This will cause the Monitor to jump to the Mini-Assembler. From Integer BASIC or 
Applesoft (disk or cassette version), enter the immediate-mode command: 
CALL -2458 
When you first invoke the Mini-Assembler, the onboard speaker beeps once. 
The prompt character for the Mini-Assembler is an exclamation point (1). 


Entry Errors 


The Mini-Assembler detects errors which you make when you enter an assembly 
language instruction. It displays the error by beeping the speaker once and 
redisplaying the instruction with a caret ( ^) under the first incorrect character in 
the instruction. The location counter does not increment; it remains unchanged 
since the last character entered so you can reenter the instruction properly. 


MONITOR COMMANDS IN THE MINI-ASSEMBLER 


At any time you are in the Mini-Assembler, you can execute Monitor commands. 
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Immediately after the Mini-Assembler prompt (1), enter a dollar sign ($), followed 
by the Monitor command. The example below shows how to examine memory 
contents from the Mini-Assembler. 

"ФІСЕЕ 


1СЕҒ- Её 
! 


This feature saves you the time spent switching back and forth between the 
Mini-Assembler and Monitor. You can enter any Monitor command while in the 
Mini-Assembler just by entering the dollar sign as the first character of input. In 
fact, you will use this feature when you leave the Mini-Assembler. 


LEAVING THE MINI-ASSEMBLER 


To leave the Mini-Assembler, use one of the Monitor commands, with the dollar 
sign prefix. To get back to the Monitor, branch to address FF69 with the $FF69G 
command. 

$Crr-B or $Crn.-C will put you in BASIC unless you're using disk-based or 
cassette-based Applesoft. For disk-based Applesoft, use $3DOG; use $0G for 
cassette-based Applesoft. 


INSTRUCTION FORMATS 


Although it is not the object of this section to teach you about programming in as- 
sembly language, there are some aspects of the Mini-Assembler which you 
should be aware of before using it. First, the Mini-Assembler maintains an instruc- 
tion pointer separate from the Monitor's memory pointer. You need to set this 
pointer before entering instructions. Second, there are various instruction formats 
used in programming the 6502 microprocessor. These formats depend largely on 
the addressing scheme used. 

The 6502 microprocessor has eleven addressing modes, but only six separate 
instruction formats. They are described below. 

The first, absolute or direct addressing, only requires the one- or two-byte 
memory address of the operand. For example: 

ANI! $303A 

The Mini-Assembler does not require a dollar sign ($) before hexadecimal 
addresses; it assumes that all addresses used are in base 16. 

The second addressing format is the immediate addressing mode, as in this 


example: LDA $$04 


Note the pound sign (+), the first character of the operand. This is an explicit 
indicator that the value 04 will load into the Accumulator. Without the pound sign, 
the Mini-Assembler interprets the instruction as ‘‘take the contents of memory 
location 0004 and load them into the Accumulator,” which is actually a default to 
absolute addressing. 
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Note also the confusing use of the term /mmediate. Do not confuse immediate 
addressing in assembly langudge with immediate execution in BASIC. The actions 
are quite different. The terms are commonplace so we will use them in spite of the 
ambiguity. 

The third addressing format is the indexed method, which looks like this: 

CMP $23.X 
or 
AND $80,.Y 

Both of these instructions are similar in that the X or Y register appears as a 
second operand. Basically, this format generates a machine language instruction 
to add the contents of the X or Y register to the address in the first operand, and 
to use this sum as the address which the instruction references. 

Next, the pre-indexed indirect format, as in this example: 


AND ($FO;X) 


indicates that the sum of the address ($FO) and the register (X) contents point to 
an address in the first 256 bytes of memory which, in turn, contains another 
address which points to the data to be used as the operand in the instruction. 
Post-indexed indirect addressing takes the following form: 
CRA (22), ү 


This instruction format uses the first operand as a pointer to a two-byte 
address, located in this case at memory location $22. This instruction adds the 
contents of the Y register to the address found at $22; the data at the derived 
address is used in the machine language instruction. The Mini-Assembler recogn- 
izes post-indexed indirect addressing when the first operand is in parentheses, as 
in the example above. 

Indirect addressing is a bit more straightforward than indexed addressing. 


Here's an example: UMP ($22FE) 


Here, the JMP instruction does not load address $22FE into the program 
counter. Instead, a two-byte address at location $22FE loads into the program 
counter. Therefore, the operand in the indirect format is actually a pointer rather 
than a literal address. 


USING THE MINI-ASSEMBLER 


As mentioned in the previous section, the Mini-Assembler maintains a location 
counter which increments by the length of each assembly language statement 
you enter. In other words, once the statement you enter is assembled into 
machine language (every time you enter an instruction), the Mini-Assembler 
calculates the length of the machine language instruction (1, 2, or 3 bytes) and 
increments the location counter for the next line. 

The first step in using the Mini-Assembler is to set the location counter. Do this 
as part of the first assembly language statement you enter. For example: 


'SDBO:LDA $04 
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Directly after the Mini-Assembler prompt, enter the base address for the as- 
sembly language code you are entering (in this case, 8DBO), followed by a colon 
(:) and the first assembly language statement. You do not have to enter a new 
location counter value for the next instruction. The Mini-Assembler calculates the 
next address unless you reset the location counter by entering another address as 
shown above. 

Once you set the location counter, enter subsequent assembly language 
instructions, one per line. After the first line, enter a blank followed by the next as- 
sembly language statement, like this: 

(ЧЕК ЕВ1Е 
This directs the Mini-Assembler to calculate the new location counter value. 


A Sample Session 


This section explains Mini-Assembler operation in step-by-step detail. The object 
of this sample session is to create a small program which uses the Apple ІІ game 
control inputs and the onboard speaker to create sounds. The procedure for this 
program is to read values from paddle O and paddle 1, using the built-in Monitor 
subroutine PREAD (at address FB1E). The value of paddle O is the interval be- 
tween clicking the speaker (Ozshortest delay, FF=longest delay), and the value of 
paddle 1 is another interval, related inversely to paddle 0 (O=longest interval, 
FF=shortest interval). 

The program will begin at 1DOO, and will use address 1CFF for storing the 
reading from paddle O. 

When you enter each line of the assembly language program, the Mini-Assem- 
bler overlays the line you entered with the current location counter value, opera- 
tion code, and operand in machine language form (also known as object code), 
along with the instruction mnemonic you entered. For example: 

1DOO- AZ oo LDX #$00 

The location counter displays at the beginning of the assembled line, followed 
by a dash. After this field, the operation code (A2 for this LDX instruction) dis- 
plays, followed by the last byte of the instruction. In the case of three-byte 
instructions (those which refer to a two-byte address), the low-order byte 
appears before the high-order byte. Lastly, the instruction mnemonic appears. 

The annotated sample session appears below. Note that each line produced by 
the Mini-Assembler appears here below the line you enter to generate it. 


tIDOO:LOX 4$00 -— Set location counter and enter first instruction 
1DOO- a2 00 LEX #SOO 
1 ШЕК ЕВ1Е -— All numbers are hexadecimal ($ prefix unnecessary) 


1По2- 20 1E FE JSR $FB1E 
! STY 1СРЕ 


1П05- ec FF 1C STY $1CFF 
! INX 
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1008- ES INX 
! JSR ЕВ1Е 


1П09- 20 1E ЕВ JSR ФҒВіЕ 
! LDA Созо 


1Doc- АП 20 СО LDA ФСОЗО 
! ПЕС ІСЕР 


1DOF- CE FF 1C DEC $1CFF 
! BNE 1DOC -- Mini-Assembler computes the relative jump (F8) 


1D12- DO Ғе BNE Ф1ПОС 
' LOA созо 

1014- AD 20 СО LDA ФСОЗО 
! INY 

1017- ca INY 

! BNE 1D14 

10186- DO FA BNE $1014 
! JMP 1000 


101A- 4C OO 1D IMP $1000 
t 


After entering this program, you should check it for accuracy. The best way to 
do this is to list the program in memory, preferably in assembly language format. 
But you will need to use the Monitor to do so as described below. 

As an additional safeguard, you may want to save the program on cassette 
(use the Monitor W command) or disk (with the BASIC BSAVE statement). 

To run the program, branch to location 1DOO. Use the G command in the Moni- 
tor, or CALL 7424 from BASIC. Fiddle with the game controls and see how they 
affect the speaker. To end the program, press Reser. 


DISASSEMBLED LISTINGS 


The Monitor contains a command which you can use to list machine language 
instructions in assembly language format, even if your Apple Il does not have the 
Mini-Assembler in ROM. The command L, for List, disassembles 20 machine 
language instructions into assembly language statements and displays them on 
the screen or other output device you select. The List command uses the location 
counter as a pointer to the next instruction to disassemble. Therefore, if you just 
enter L after entering the program above, disassembly will start with address 
1D1D, and it will not list any of the program you entered. 

It is good practice to set the location counter when using the List command. 
Here is a disassembled listing of the sound program: 

!$1DOOL 


iDoo- a2 00 LDX #$00 
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1002- 20 1E FB JSR ФЕВІЕ 
1Dos- SC FF 1C STY $1CFF 
10032- ES INX 

1П09- 20 1E ЕВ JSR $FRIE 
1DOC- AD 30 CO LDA $CO30 
1D0F- CE FF 1C DEC $1CFF 


1D12- Do FS BNE $1DOC 
1D14- АП зо СО LOA %СОЗО 
1D17- сз ІМҮ 

1018- DO FA ENE $1014 
101A- 4C OO 1D JMP $1000 
1011- vF ??? 

101Е- 4Е А5 12 LSR $1245 
1D21- А4 96 LOY $96 
1D23- A3 ??? 

1D24- Do А4 BNE $1CCA 
1D26- EF ??? 

1D27- А4 62 LDY $62 
1D29- А2 70 LDX #$70 


In this case, the last eight disassembled instructions are immaterial, since the pro- 
gram ends at address 1D1A. 

Note that the List command is a Monitor facility, independent of the Mini-As- 
sembler (hence the dollar sign prefixing the command). By entering L ($L in the 
Mini-Assembler) and pressing Return without setting the location counter, you 
direct the Monitor to disassemble the next 20 instructions it finds after those just 
listed. 


TESTING AND DEBUGGING PROGRAMS 


Together with the Mini-Assembler, the Monitor in the standard Apple ІІ furnishes 
you with debugging features which are very helpful when you are programming in 
assembly language. Programs in low-level languages are probably the hardest to 
debug and test. Instead of simply printing contents of variables, you must inspect 
memory locations, registers, and the program itself. Two Monitor commands, 
Step and Trace, are used for this purpose. 

The Step and Trace commands are not available on versions of the Apple Il 
with the Autostart Monitor. 


The Step Command 


While it is easy enough to try testing an assembly language program by witness- 
ing the symptoms of its operation, this is frequently not a very efficient or effec- 
tive method of isolating errors. If the program is small enough, it is possible to run 
it step by step, checking the results of each machine language instruction after 
the Apple Il performs it. The Step command does just that. 

When you execute the Step command, the Monitor disassembles and displays 
the instruction pointed to by the location counter, executes it, displays the con- 
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tents of the microprocessor registers, and returns control of the Apple Il to the 
Monitor. 

The format of the Step command is an optional address parameter (to set the 
location counter) followed by the letter S. 

The Step command below performs the first instruction in the sample sound 
program. The contents of the X register display as O. The other three registers 
whose contents display are unchanged. 


+10005 
1000- А2 00 LDX #00 
A-FF X-00 Y-8C P-32 S-F8 

E 


You can alternate between the Step command and other monitor commands 
(such as examine memory). To see this in action, step through the sample sound 
program until you get to the STY instruction at memory location 1DO5. You will 
have to enter the S command nine times, since the JSR instruction at location 
1002 calls а subroutine at location FB1E and you must step through it before you 
get back to 1DO5. Once you're there, use the examine memory Monitor command 
to check location 1CFF. The instruction at address 1005 stores the reading of 
paddle O at address 1CFF. 


#5 

1005- ec FF 1С STY $1CFF 
A=00 X200 Ү=00 Р=32 S=FS 
*1zZ£cFF 

1ІСЕЕ- 00 

% 


As you can see from the memory examine command, the contents of the Y 
register (3F) are now stored at address 1CFF. You can intersperse most Monitor 
commands with the Step command. 


The Trace Command 


Sometimes a program may be too long to allow you to execute each instruction 
step by step. Instead, you may want to see each program step execute, but only 
interrupt the execution of the program when it is necessary to do so. The Moni- 
tor's Trace command performs this function. Its output is similar to the Step com- 
mand, except that it saves you the effort of entering a Step command for each 
instruction the Apple ll executes. In order to stop the Trace command, you can 
press the Reset key or imbed а BRK assembly language instruction in the pro- 
gram; when the Monitor encounters this instruction it returns control of the com- 
puter to you (via the Monitor). 

The format for the Trace command is an optional address followed by the let- 
ter T. Here is the first part of a trace of the sample sound program: 
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3313 DOOT 
1Doóo- a2 00 LEX #SOO 
A=FF X=00 Y=8C Р=32 S-F6 
1002- 20 1E FE JSR $FRIE 
A-FF X=00 Y=8C P=32 S=F4 
FE1E- АП 70 СО LDA %СО7О 
A=00 X=00 Y=8C P=32 S=F4 
FB21- AQ ОО LDY #$00 
A=00 X=00 Y=00 P=32 S-F4 
FE23- EA NOF 
A=00 X200 Ү=00 Р=32 S-F4 
FE24— EA МСР 


A=00 Х=00 Ү=00 Pz32 5-Ғ4 
ҒВ25- ЕП 44 СО LDA $CO64;X 
A=00 X-00 Y=00 Е=32 5-Ғ4 


FE28- 10 04 ЕРІ. ФҒЕ2Е 
A=00 Х=00 Y=00 Р=32 S-F4 
FBZE- 60 RTS 


А=00 X-00 Y=00 Pz32 3=F4 
10035- ec FF іс 
A=00 X=00 Ү=00 Р=32 
iios- ES 
4-00 X=01 Y=00 P=30 
1009- 20 1E FR jJ 
A=00 X-01 Ү=00 P=30 S=F4 
FE1E- AD 70 CO LDA $C070 
A=27 X-01 Y=00 P=30 S=F4 
ҒЕ21- AQ оо ШҮ t$Ooo 
=27 X01 Ү=00 P232 S=F4 
ЕВ2З-- ЕА МОР 
А=27 Х=01 Ү=00 Р=32 S=F4 
ҒЕ24- EA NOP 
6-27 Х=01 Y=00 Р=32 S=F4 
FB25- BD 44 СО LDA COLA X 
4-27 X=01 Y=00 P=30 5-Ғ4 


б 


к 
eain zu At 
X Hoxid- 


$1CFF 


T 
> 


^ 
e 


ФЕБІЕ 


ҒвВ28- 10 04 BFL ФҒВ2Е 
A=27 X-01 Ү=00 P=30 S-F4 
ERIE- AN RTS 


The disadvantage of using the Trace command over the Step command is that 
you have less control over the execution of each step of the program. When you 
initially enter the program, you have to put in BRK instructions at key points. 
These are junctions in the logic of the program. Of course, you can replace these 
BRK instructions with NOP instructions (no operation code), but this can be dis- 
tracting once you have finally debugged the program. 

Additionally, the Trace command works at a fraction of the speed of the as- 
sembly language program. For instance, try substituting the instruction in the 
sample sound program at address 1D1A with a BRK instruction. By entering the 
command 1DOOG this routine takes a fraction of a second to execute. However, 
by entering 1DOOT, the program takes anywhere from 60 to 70 seconds to 
execute. Therefore, if you have a large program to test, be conservative with the 
Trace instruction if you want it to be any help at all. 
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More About the Location Counter 


As mentioned before in the section on the Step Command, you can use most 
Monitor commands alternately with the Step and Trace commands. There are 
some exceptions to this rule, however. The List, Go, and user-defined CrRL.-Y 
commands all modify the location counter when you enter them. This will disrupt 
the flow of the program you are stepping through or tracing unless you reset the 
location counter after executing one of these commands. The example below 
shows how the location counter's value is disrupted by using one of these com- 
mands. 


*1DOO0S 
1000- A2 оо LIX #$00 
A=42 X=00 Y=00 Р=32 S-F3 
© 
iDoz- ZO 1E FE ASR ФЕБІЕ 
A=42 X=00 Y=00 P232 SzF3 
ж -— List command here 
FELIE- an 70 CO LDA $Cco70 
FB21- А0 OO LDY 4$00 
ҒВ2з- EA МОР 
FB24- EA NOP 
FB25- ВП 64 CO LDA $C064, X 
ЕВ28- 10 04 BPL $FB2E 
FEZA- cs INY 
FBZB- po FS BNE ФҒВ25 
FE2L- за DEY 
FB2E- 60 RTS 
FE2F- A? оо LDA $00 
FB31- 88 43 STA $42 


FB33- АП 56 СО LDA %ФСО56 
FB36- aD 54 co гра %С054 
FB39- АП 51 CO га %С051 
FB3C- A? оо LDA Я%00 

ЕВЗЕ- ҒО ОВ BEQ $FBAB 
FB40- АП 50 СО LDA %СОЗО 
ҒВ4з- АП 53 СО LDA $COSS 
ҒВ46- 20 36 F8 JSR $F334 


жб <- Changes location counter, so 
next step is at $FB49 
FB49- A? 14 LDA $14 instead of $FB1E 
A=14 X200 Y=00 P-30 S=F4 
#5 
FB4B- 35 22 STA $22 
A=14 Х=00 Ү=00 P=30 S=F4 


Useful Monitor Subroutines 


In some cases, BASIC is not powerful enough to perform all of the functions you 
may need in a program. This, of course, is one reason why programmers resort to 
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assembly language subroutines for their BASIC programs. This section shows 
how to reference them from a BASIC program. 

By weaving assembly language programs in with a BASIC program, you can 
create as many problems as you intended to solve. Where in memory are you 
going to put the assembly language programs? Remember, the Apple ІІ memory 
contains four large reserved areas (text/low-resolution graphics pages and both 
high-resolution graphics pages). DOS and the Applesoft interpreter may take up 
memory too. Locating a program where it will not cause problems is dependent on 
memory size and the version of Apple ІІ you use. 

The Monitor is your best source for assembly language subroutines for three 
reasons: first, being in ROM, you don't need to worry about relocating code; sec- 
ond, the Monitor routines have already been debugged; and lastly, the intrinsic 
routines do not take up one byte of additional memory. The useful Monitor 
subroutines are listed in Appendix D. 


Incorporating the Subroutine 


If you decide to use a Monitor subroutine in a BASIC program, first be sure that 
there is no BASIC equivalent for it. This will save you the trouble of making a pro- 
gram more complicated than necessary. Next, check whether the assembly 
language subroutines need parameters passsed from the BASIC program. If you 
have to set values in the microprocessor registers before executing the 
subroutine, or if the result of a subroutine resides in a register after execution, you 
will have to use extra assembly language instructions to interface with BASIC. 
Most Monitor subroutines need no parameters from BASIC; those which do fre- 
quently have a BASIC equivalent anyway. 

Once you know which subroutine to use, you may want to document it in a way 
which makes the meaning clear. For instance, CALL —936 clears the text screen 
and places the cursor in the upper lefthand corner of the screen. One way of mak- 
ing the CALL statement more descriptive is to set a variable at the beginning of 
the program, as follows: 

10 CLSCREEN--936 
and to reference it later in the program: 
1510 CALL CLSCREEN 


This makes the context of the CALL statement clearer to someone who has to 
read it, but it does add one statement to the program. These finer elements of 
style will make your program easier to read and debug. 


Problems to Avoid 


If you have an editor/assembler available for the Apple Il, it is easy to relocate pro- 
grams by resetting the origin point and reassembling. However, if you wrote a 
machine language subroutine with the Mini-Assembler, and the subroutine is 
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designed to be used with BASIC, you may run into problems which force you to 
rewrite the subroutine for versions of the Apple Il with different memory sizes. 
This will happen if you use memory locations used by DOS, the graphics pages, or 
disk-based or cassette-based Applesoft. Try to use Monitor subroutines wherever 
possible. 

If you program in Applesoft, always use the USR function if you have to pass 
parameters to and from the subroutine, instead of the CALL statement. 
Addresses 9D through A3 store the value of the parameter passed by USR, and 
you can use this area for parameters to pass back to BASIC. Use the POKE state- 
ment to put a JMP instruction in locations 10 through 12 (OA through OC hex- 
adecimal). These locations must contain a JMP instruction to the beginning of the 
machine language subroutine invoked by USR. 


INTEGRATING YOUR PROGRAM 
WITH BASIC 


In BASIC, the statements LOMEM: and HIMEM: protect your assembly language 
program from being written over by BASIC. There are some requirements in set- 
ting up an assembly language program if you also intend to have disk-based or 
cassette-based Applesoft or the Disk Operating System in memory at the same 
time. The general procedure for using an assembly language subroutine or pro- 
gram with BASIC and DOS is as follows: 


1. Boot DOS. 

2. Load the Applesoft interpreter from disk or cassette, if necessary. 
3. Set LOMEM: and HIMEM: values. 

4. Load the assembly language program. 

5. Load the BASIC program from disk or tape (or type it in). 


The Disk Operating System resets HIMEM: after you load it from the disk into 
memory. The Applesoft interpreter resets LOMEM: after it is loaded. You reset 
LOMEM: or HIMEM: to allow room for your assembly language programs, and 
then load them into that safe space. Subsequently loading and running a BASIC 
program affects only the remaining memory between LOMEM: and НІМЕМ:. 

For more help on finding space for your assembly language program, check the 
memory maps in Appendix G. Also, refer to the discussion of LOMEM: and 
HIMEM: in Chapter 8. 


Compendium of BASIC Statements 
and Functions 


This chapter describes the syntax for all Apple ІІ BASIC statements and functions. 
Statements are described first, listed in alphabetical order; then functions are de- 
scribed, also in alphabetical order. 

This chapter serves as a reference for all statements and functions. Chapters 3 
through 7 describe programming concepts. They also give examples of state- 
ments and functions used in programs. 


IMMEDIATE AND PROGRAMMED MODES 


Most statements can be executed in immediate or programmed mode. Unless 
otherwise stated, you can assume that a statement can be used in both modes. 
Exceptions are identified. Some statements can be used in one mode, but not the 
other; other statements can be used in both modes, but only one mode is practi- 
cal. 

Some statements are Disk Operating System (DOS) statements. They can be 
used as shown in immediate mode. In programmed mode, however, they must be 
issued as part of a PRINT statement string, the first character of which is Ctrl-D 
(ASCII code 4). Thus, the following two statements are equivalent: 

JCATAL UG 
JFRINT СНКФ (4) 3 "CATALOG" 

Note that instead of using CHR$(4) as shown above, you can type а quotation 

mark, followed by CrRL-D, and then another quotation mark. On the screen it will 
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seem you have only pressed the quotation mark key twice. The CraL-D character 
is there even though you can't see it. 


BASIC VERSIONS 


All statements and functions are available in both Integer BASIC and Applesoft 
unless otherwise stated. Where a statement or function works differently in the 
two versions of BASIC, the differences are noted. 


NOMENCLATURE AND FORMAT CONVENTIONS 


We use a standard scheme for presenting the general form of each statement and 
function. Listed below are the punctuation, capitalization, and other mechanical 
conventions we use. 


() Braces indicate a choice of items. One of the enclosed 
items must be present; braces do not appear in an 
actual statement. 

(] Brackets indicate that the enclosed parameter is 
optional; brackets do not appear in an actual 
statement. 

Ellipses indicate that the preceding item can be 
repeated; ellipses do not appear in actual statements. 


line A beginning line number is implied for all programmed 

numbers mode statements. 

other All other punctuation marks — commas, semicolons, 

punctuation quotation marks, and parentheses — must appear 
as shown. 

UPPER Upper-case words and letters must appear exactly as 

CASE shown. 

italics Generic terms are italicized. The programmer supplies 


` the exact wording or value, according to the generic 
term definitions listed below. 


The following italicized generic terms are used in statement and function 
definitions. Any italicized terms not listed here are peculiar to the statement in 
which they appear. They are defined in the text that describes that statement. 


col Low-resolution graphics column number; a numeric 
expression which has a value between O and 39. 
colh High-resolution graphics column number; a numeric 
expression which has a value between O and 279. 
const Any numeric or string constant. 


Dn А disk drive number which must be specified as DO or D1. 
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expr Any numeric string, relational, or Boolean (Applesoft 
only) constant, variable, or expression; any valid 
combination thereof. 

expr$ Any string constant, variable, or expression. 

exprnm Any numeric constant, variable, or expression. 

filename Any disk file name. 

line Any BASIC program line number. 

line, One of many BASIC program line numbers. 

memadr А numeric expression, variable, or constant that 
evaluates to any memory address. Memory addresses 
may range from —65535 to 65535 (decimal), where 
-65535 is the same as 1, —65534 equals 2, etc. 

memloc Any memory location specified by an integer constant 
between О and 65535 (decimal) or $0 and $FFFF 
(hexadecimal). Hexadecimal constants are identified 
by a dollar sign ($) prefix. 

message Any text string enclosed in quotes. 

row Low-resolution graphics row number; a numeric 
expression which has a value between O and 47. 

rowh High-resolution graphics row number; a numeric 
expression which has a value between O and 191. 

Sn Slot number for input or output; must be SO, S1, S2, 
S3, S4, S5, S6, or S7. 

var In Integer BASIC, any numeric or string variable. In 
Applesoft, any numeric, integer, or string variable. 

varnm Any numeric variable name. 

var (sub) In Integer BASIC, any subscripted numeric variable. In 
Applesoft, any subscripted integer, numeric, or string 
variable. 

Vn An identifying disk volume number (between VO and 
V255). 

STATEMENTS 
APPEND 


Opens a file (see OPEN), and positions the file pointer at the end of the file. 


Format: 
APPEND filename [,Dn] [,Sn] [Мл] 


264 APPLE Il USER'S GUIDE 


TABLE 8-1. Machine Language Fix for APPEND 


MACHINE LANGUAGE 6502 ASSEMBLY LANGUAGE 
poema [nena | wnat INN NN 


169 The Monitor routine 
0 at $FDED outputs 
the character in 
4c JMP $FDED register A ($0 in this 
case) to the currently 
selected output device, 
the disk. See Appendix D. 


А memory buffer of 595 bytes is allocated for the text file specified. The file must 
be a sequential file. The WRITE command can now be used to store information 
on the file, starting at the first unused byte. This will be immediately following the 
last character in the file unless there are unused bytes in the middle. 

Occasionally, APPEND will not start at the first unused byte in the file (often the 
end of the file). Instead it starts at the beginning of the Не. (Horrors!) To make 
sure this doesn't happen, your program should always write an end-of-file marker 
before closing a file it has written to. The short machine language subroutine in 
Table 8-1 does the trick. POKE this into memory anywhere there are five free 
bytes (locations 768 through 772 are OK unless you're using them for something 
else). Then call the subroutine (use CALL) just before closing the file. 

If the file does not exist on drive Ол of slot Sn, the FILE NOT FOUND error 
message is displayed. If the disk in drive Dn of slot Sn is not volume Ул, the 
VOLUME MISMATCH error results. VO will match any disk. If the file is already 
open, APPEND closes it and reopens it (see CLOSE). 

Ол, Sn, and Vn can be specified іп any order. If Dn or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Vn is absent. Also, n can be absent; 
DO, SO, or VO will be used. 

APPEND is a DOS command, requiring PRINT and Catt-D in programmed 
mode. 

May not be used in immediate mode. 


AUTO 


Sets automatic line numbering mode in Integer BASIC. 


Format: 
AUTO /ine increment] 


Line numbers are automatically displayed each time you key RETURN, starting 
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with //ле, and increasing each time by increment, which defaults to 10 if not 
specified. Type CrRL-X to erase an automatic line number; automatic line number- 
ing resumes unless MAN is entered on the next line (see MAN). 

Can be used only in immediate mode. 

Not available in Applesoft. 


BLOAD 


Retrieves a binary file from the disk and stores it in the specified section of 
memory. 


Format: 
BLOAD filename L Amemloc] LDn] LSn] [Ул] 


If the A parameter is absent, the specified file is placed in memory beginning at 
the memory location from which the file was saved (see BSAVE). If the A 
parameter is present, the file goes into memory at memioc. 

BLOAD must be used with care. Anything already in the section of memory 
where it is placed (such as your program, Applesoft, DOS, etc.) will be overwrit- 
ten. 

If the file does not exist on drive Ол of slot Sn, the FILE NOT FOUND error 
message is displayed. If the disk in drive Dn of slot Sn is not volume Ул, the 
VOLUME MISMATCH error results. 

Dn, Sn, and Vn can be specified іп any order. If Dn or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Vn is absent. 

This is a DOS command, requiring PRINT and CrRL-D in programmed mode. 


BRUN 


Retrieves a binary file (which should be a machine language program), stores it in 
the specified section of memory, and then executes a machine language jump 
(JMP in 6502 assembly language) to the starting memory location. 


Format: 
BRUN filename [,Amemloc] LDnl (Өлі LVn] 


If the A parameter is absent, the specified file is placed in memory beginning in the 
memory location from which the file was saved (see BSAVE). If the A parameter is 
present, the file goes into memory at memfoc. 

A machine language program may work properly at only one memory location. 
Check carefully for instructions that are address dependent before loading to a 
new memory location. BRUN overwrites anything in the section of memory in 
which it stores the file; this could be awkward if DOS or Applesoft is destroyed in 
the process. 
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If the file does not exist on drive Ол of slot бл, the FILE NOT FOUND error 
message is displayed. If the disk in drive Dn of slot Sn is not volume Ул, the 
VOLUME MISMATCH error results. 

Ол, Sn, and Ул сап be specified іп any order. If Dn or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Vn is absent. 

This is а DOS command, requiring PRINT and Ста. -О in programmed mode. 


BSAVE 


Creates a disk file and saves a section of the Apple II's memory on it, in binary. 


Format: 
BSAVE filename ,Amemloc ,Lilength [Оп] [Sn] [Vn] 


The A parameter specifies the starting address of the memory section to save. 
The L parameter specifies the number of bytes to save. /ength must be an integer 
in the range O through 32767 (decimal). It may be either a decimal or hexadecimal 
constant. Hexadecimal constants are identified by a dollar sign ($) prefix. 

If the file does not exist on drive Ол of slot Sn, the FILE NOT FOUND error 
message is displayed. If the disk in drive Ол of slot Sn is not volume Ул, the 
VOLUME MISMATCH error results. 

Ол, Sn, and Ул сап be specified in any order. If Dn or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Vn is absent. Also, n can be absent; 
DO, SO, or VO will be used. 

This is a DOS command, requiring PRINT and Ctrt-D in programmed mode. 


CALL 


Branches to a machine language subroutine at a specified location. 


Format: 
CALL memadr 


CALL can be used with subroutines that you write yourself, as well as with various 
intrinsic subroutines which are listed in Appendix D. 


CATALOG 


Displays a list of all files on the specified disk. 


Format: 
CATALOG [D^] [S7] 
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CATALOG first prints DISK VOLUME followed by the volume number of the disk. 
If the volume parameter V7 is included in the CATALOG command, it is ignored. 

The list of files on the disk is displayed below the volume number. For each file, 
CATALOG prints a code letter indicating the type of file, the number of sectors 
required to store the file, and the name of the file. An asterisk appears to the left 
of the file type if the file is locked (see LOCK). The file types and their codes are: 


| Integer BASIC Program 


A Applesoft Program 
T Text File 
B Binary (Machine Language) File 


If a file length exceeds 255 sectors, the file length is displayed modulo 255; 
i.e., O is printed if the file length is 256, 1 if it is 257, etc. 

Ол and Sn can be specified іп any order. If Dn or Sn is absent, the last- 
referenced drive or slot is used. 

This is a DOS command, requiring PRINT and Crat-D in programmed mode. 


CHAIN 


Loads and runs an Integer BASIC program from the disk, without clearing the 
values of any variables or arrays. 


Format: 
CHAIN filename [Оп] (Өлі! [Vn] 


The CHAIN command may only be used in Integer BASIC, and may only be used to 
load an Integer BASIC program. 

If the file does not exist on drive Ол of slot Sn, the FILE NOT FOUND error 
message is displayed. If the disk in drive Ол of slot Sn is not volume Vn, the 
VOLUME MISMAT CH error results. 

Ол, Sn, and Vn can be specified іп any order. If Dn or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Vn is absent. Also, n can be absent; 
DO, SO, or VO will be used. 

This is a DOS command, requiring PRINT and Crat-D in programmed mode. 


CLEAR 


This Applesoft statement assigns O to all numeric variables and numeric array ele- 
ments. Also assigns a null value to all string variables and string array elements. 


Format: 
CLEAR 
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Executing this statement is equivalent to turning the Apple ll off, then turning it 
back on and reloading the program into memory. А program will continue to run 
following CLEAR providing the effects of the CLEAR statements do not adversely 
affect program logic. 

For Integer BASIC, use CLR. 


CLR 


This Integer BASIC command assigns O to all numeric variables and array ele- 
ments, and assigns a null value to strings. 


Format: 
CLR 


Also undimensions all arrays and strings. You can still print array values after 
executing a CLR statement, as long as no variables have been assigned values in 
the interim. 

CLR can be used only in immediate mode. 

For Applesoft, use CLEAR. 


CLOSE 


Deallocates the buffer used by the specified disk file, and if the last operation on 
the file was WRITE, saves anything left in the output buffer on the file. 


Format: 

CLOSE [filename | 
You must CLOSE any file you have used the WRITE statement with in order to 
avoid losing data. If filename is present, only that file is closed. If filename is not 
present, all files are closed (except a controlling EXEC file). 

Occasionally a sequential file will exactly fill a sector as it is closed. Under these 
conditions, a subsequent APPEND will occur at the beginning of the file rather 
than the end. To forestall this, call the short machine language subroutine in Table 
8-1 just before the CLOSE statement. You can POKE the subroutine anywhere 
there are five free bytes (e.g., locations 768 through 772 unless otherwise in use). 

This is a DOS command, requiring PRINT and Crat-D in programmed mode. 


COLOR- 


Sets the color for low-resolution graphics. 


Format: 
COLOR= exprnm 
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TABLE 8-2. Low-Resolution Color Codes 


Black 4 |0агк Green 8 Green 
Magenta 5 [Grey 9 Yellow 
Dark Blue 6 |Medium Blue} 10 Aqua 
Purple 7 |Light Blue 11 White 


Until the next COLOR statement, all PLOT, VLIN, and HLIN statements will be in 
the color specified. The color codes are listed in Table 8-2. The exprnmmust һауе 
a value in the range O to 255; real values are converted to integers. Values greater 
than 15 repeat the colors shown above (О, 16, 32, etc. are black, and so on). 
COLOR = O if not previously specified. 

COLOR has no effect if used while in high-resolution graphics mode. When 
used while in text mode, COLOR is one factor in determining which character is 
placed on the screen by a PLOT instruction. For a detailed description of this 
feature, see PLOT. 


CON 


This Integer BASIC command resumes program execution at the next instruction 
after a halt. 


Format: 

CON 
CON operates after execution has been halted by Ста.-С, and sometimes after 
Reser. If there is no interrupted program, CON simply locks up the system. А pro- 
gram cannot be continued after it is interrupted Бу CraL-C during an INPUT state- 
ment. 

If a program line has been changed or added, or an error message generated 
since program execution was halted, CON will work sometimes, but may produce 
an error message or lock up the system. 

CON can be used only in immediate mode. 

For Applesoft, see CONT. 


CONT 


This Applesoft command resumes execution at the next instruction after a halt. 


Format: 
CONT 
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CONT operates after execution has been halted by STOP, END, or Crn.-C. If an 
INPUT statement is interrupted by CrRL-C, the program cannot be continued. If 
there is no interrupted program, or a program line has been changed or added, or 
an error message generated since program execution was halted, CONT will pro- 
duce the message ?CAN'T CONTINUE ERROR. 

For Integer BASIC, see CON. 


DATA 


Creates a list of values to be assigned by READ statements in Applesoft. 


Format: 

DATA const [ ,const. . ] 
DATA statements may appear anywhere in a program; they need not be executed 
to be accessed by a READ command. 

The DATA statement specifies either numeric or string values. String constants 
are usually enclosed in quotation marks; the quotes are not necessary unless the 
string contains blanks (spaces), commas, or colons. А quotation mark cannot be 
represented in a const ; it must be specified using a CHR$(34) function. 

One or more of the const parameters can be null, i.e., nothing but blanks. A null 
const is assigned as zero to a numeric variable, or a null string (") to a string 
variable. 

You will receive no error message if you enter a DATA statement in immediate 
mode, but the elements will not be accessible to a READ command. 

Not available in Integer BASIC. 


DEF FN 


The DEF FN statement allows special purpose functions to be defined and used 
within Applesoft programs. 


Format: 

DEF FN^var (arg) = exprnm 
Real variable nvar identifies the function, which is subsequently invoked using the 
name FN^var. 

The function is defined by exprnm. arg is a dummy variable name which can 
(and usually does) appear in exprnm. Its use in a DEF FN statement has no effect 
on any other variable with the same name elsewhere in the program. 

When ҒМлуаг is invoked, the value of the dummy variable argis specified by а 
numeric expression, variable, or constant. The values of all other variables in 
exprnm must be defined before FNnvar is invoked. See also FN in the Functions 
section of this chapter. 
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The entire DEF FN statement must appear on a single program line. However, a 
previously defined function can be included in exprnm , so user-defined functions 
of any desired complexity can be developed. A user-defined function cannot, 
however, invoke itself directly or indirectly (by invoking a function which even- 
tually invokes it). 

The function name nvar сап be reused, and therefore redefined by another DEF 
FN statement appearing later in the same program. 

Not available in Integer BASIC. 

The DEF FN definition statement is illegal in immediate mode. However, a user- 
defined function that has been defined by executing a DEF FN statement since the 
last NEW, CLR, or LOAD command can be referenced in an immediate mode 
statement. 


DEL 


Eliminates the specified program lines. 


Format: 

DEL /ine,, line, 
All program lines greater than or equal to /ine, and less than or equal to //ne, are 
removed from the program currently in memory. If /ine, does not exist, the dele- 
tion starts at the next higher line number. If /ine, does not exist, the deletion ends 
at the next lower line number. 

DEL must be followed by two line numbers which are separated by a comma. 
Neither line number can be negative, and the second line number must be greater 
than or equal to the first. If the line numbers are identical, one line (at most) is 
deleted. 

DEL may only be used in immediate mode in Integer BASIC. 

If DEL is used in programmed mode (possible only in Applesoft), the indicated 
deletions take place and the program halts. CONT will not continue the program in 
this case. 


DELETE 


Erases a file from the disk. 


Format: 
DELETE filename [,Dn] Sa] [Vn] 
The file with the specified name is removed from the disk. 
If the file does not exist on drive Ол of slot Sn, the FILE NOT FOUND error 
message is displayed. If the disk in drive Ол of slot Sn is not volume Ул, the 
VOLUME MISMATCH error results. 
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Ол, Sn, апа Ул сап be specified in any order. If Dn or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Vn is absent. Also, л can be absent; 
DO, SO, or VO will be used. 

This is а DOS command, requiring PRINT and CrnL-D in programmed mode. 


DIM 


Reserves space in memory for an array or string. 
Because of the extensive differences between Integer BASIC and Applesoft, 
DIM is discussed below as it operates in each language. 


Integer BASIC Format: 
DIM var (sub) Lvar (sub). . 1 


Only numeric arrays of one dimension and simple string variables may be dimen- 
sioned in Integer BASIC. 

When an array is dimensioned, space is set aside in memory for the number of 
elements equal to sub plus 1. They are numbered O through sub. Element O of an 
array is identical to the simple variable of the same name (e.g., А(О)-А). 

DIM statements declare the maximum lengths of string variables. In this case 
Sub is the string length. 

Every subscript sub must be between 1 and 255 in a DIM statement. Aside 
from this, the maximum allowable dimensions are limited by available memory. 

If you reference an array using a subscript greater than the largest subscript 
declared in the DIM statement for that array, the message *** RANGE ERR 
occurs. If you attempt to use more characters in a string than it was dimensioned 
for, the message *** STRING ERR is generated. 

DIM does not assign the elements of Integer BASIC arrays any particular value 
when it is executed. Therefore, you must initialize every array (e.g., to zero) after 
dimensioning it. String variables, on the other hand, always have a null value after 
first being dimensioned. 


Applesoft Format: 
DIM var (sub sub. . .]) Lvar (subl,sub. . . 1). . .] 

The DIM statement identifies arrays with one or more dimensions as follows: 
var(sub,) Single-dimension array 
var(sub;,sub,) Two-dimension array 
var(sub;,,sub,,sub,...) Multiple-dimension array 

Applesoft supports three types of arrays: integer, real, and string. Each element 
of an array is of the type specified by the variable name for the array. The number 


of dimensions in an array is determined by the number of subscripts in the DIM 
statement. When an array is referenced, each subscript must fall within the range 
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O through sub, where sub is the corresponding subscript of the same variable in 
the DIM statement. 

The number of dimensions in an array is limited by the amount of memory 
available. The maximum number of dimensions an array can ever have is 88, and 
this is only possible when most of the subscripts are O. A DIM statement with 89 
or more subscripts, or one that otherwise exceeds memory limitations will pro- 
duce the message ?ООТ OF MEMORY ERROR. 

If you attempt to use an array with a subscript that is out of range or with the 
wrong number of subscripts the message ?BAD SUBSCRIPT ERROR will appear. 

If an array is referenced before a DIM statement for that array has been 
executed, Applesoft assigns a default value of 10 to each subscript. The array is 
thereafter treated just as if a DIM statement with a subscript of 10 for each 
dimension had been executed. 

An array can never be dimensioned twice, even one that has been dimensioned 
by default. If you attempt to dimension an array that has already been dimen- 
sioned, you will be treated to the message ?REDIM'D ARRAY ERROR. 


DRAW 


This Applesoft statement draws a high-resolution graphics shape on the screen. 


Format: 
DRAW exprnm [ AT colh, rowh] 


The shape identified by the integer value of exprnm is drawn in the color deter- 
mined by the last-executed HCOLOR statement. The scale and rotation of the 
shape must be set by SCALE and ROT commands before the DRAW is executed. 

Starts drawing the shape at the location given by the integer values of numeric 
expressions colh and rowh. |f you do not specify a location іп the DRAW state- 
ment, the shape starts at the last point plotted by the last-executed DRAW, 
XDRAW, or HPLOT command. 

The shape number specified (exprnm) must be between O and the number of 
shapes in the shape table (which must not exceed 255), inclusive. 

Avoid using DRAW if there is no shape table in memory. The system might lock 
up, or you might find random shapes drawn on the screen. If your program 
extends into the high-resolution graphics portion of memory, some or all of it 
could be destroyed. 

Not available in Integer BASIC. 


DSP 


Displays the changing values of the specified variable as an Integer BASIC pro- 
gram progresses. 
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Format: 


DSP var 
The value of variable var and the current line number are displayed whenever the 
value of that variable changes. This display may interact with your program's out- 
put, rendering one or both illegible. RUN cancels all DSP instructions. Use CON or 
GOTO when you are debugging with DSP in immediate mode. 
To turn off DSP, use NO DSP. 
Not available in Applesoft. 


END 


Causes a program to halt. 


Format: 
END 


No message is displayed. In Integer BASIC, END must be the last instruction 
executed or the warning %%% NO END ERR is displayed. END is entirely optional in 
an Applesoft program. 

Cannot be used in immediate mode in Integer BASIC. 


EXEC 


Executes a disk text file as if each character in the text file were entered on the 
keyboard. 


Format: 
EXEC filename [,Вп ) [Ол] [50] [Vn] 


A text file to be used with EXEC consists of some combination of BASIC com- 
mands, DOS commands, and program lines. When EXEC is executed, the first line 
of the specified file is read from the disk. If a command, it is executed 
immediately; if a program line, it is added to any program lines in memory, just as 
if you had entered it directly from the keyboard. 

An EXEC file can be used to enter an entire program, list it, run it, save it on the 
disk, change it, or anything else that can be done from the keyboard. You can 
even use an EXEC file to create and execute a second EXEC file. 

The R parameter, if present, specifies which field of the file is first executed. 
When used with EXEC, the R parameter always counts from the beginning of the 
file: the first field in the file is field O, the second is field 1, etc. The number follow- 
ing R must be an integer constant in the range O through 32767. If Rn specifies 
the first field following the end of the file, nothing happens. If it specifies two 
fields or more past the end of the file, the END OF DATA message occurs. 
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If an INPUT statement is executed while an EXEC file is open, the response is 
taken from the EXEC file. 

When the last line in the file has been executed, the EXEC file closes itself (see 
CLOSE). When an EXEC command is encountered in a controlling EXEC file, the 
original file is closed and any further commands in it are ignored; the new EXEC 
file is opened and executed normally. 

If the file does not exist on drive Dn of slot Sn, the FILE NOT FOUND error 
message is displayed. If the disk in drive Dn of slot Sn is not volume Vn, the 
VOLUME MISMATCH error results. 

Ол, Sn, and Ул can be specified іп any order. If Dn or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Vn is absent. Also, n can be absent; 
DO, SO, or VO will be used. 

This is a DOS command, requiring PRINT and CrRL.-D in programmed mode. 


FLASH 


This Applesoft statement turns on flashing video mode. 


Format: 

FLASH 
All output from subsequently executed PRINT statements will appear alternately 
as white-on-black and black-on-white characters. Error messages are similarly 
affected. However, characters echoed to the screen by INPUT statements are 
unaffected, as are any previously displayed characters. 

FLASH works by slightly altering the standard ASCII codes. Therefore any 
characters sent to the disk in flash mode will be saved with incorrect codes. When 
read back in, the wrong characters will result. 

Not available in integer BASIC. 


FN 


Listed in the Functions section of this chapter. See also DEF FN. 


FOR 


Starts a loop that repeats a set of instructions until an automatically incremented 
variable attains a certain value. 


Format: 
FOR varnm = exprnm, TO exprnm, [STEP exprnm,] 
When FOR is first executed varnm is assigned the value of exprnm,. The state- 
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ments following FOR are executed until a NEXT statement is reached. varnm is 
then incremented by exprnm, lor by 1 if the STEP clause is not present). After 
that, the new value of varnm is compared to the value of exprnm;. The sense of 
the comparison depends on the sign of exprnm;. If the sign is positive and the 
new value of varnm is less than or equal to exprnm,, execution loops back to the 
statement just after the FOR. The same thing happens if the sign of exprnm; is 
negative and the new value of varnm is greater than or equal to exprnm,. On the 
other hand, execution continues with the instruction that follows the NEXT if 
varnm is greater than exprnm, (exprnm, positive) or less than exprnm, (ехргпт; 
negative). Because the comparison occurs after incrementing varnm, the instruc- 
tions between FOR and NEXT are always executed at least once. 

In Integer BASIC varnm must be an integer variable. In Applesoft varnm must 
be a real variable. It can never be a string variable. 

The start, end, and increment values are determined from exprnm,, exprnm,, 
and exprnm, only once, on the first execution of the FOR statement. If you change 
these values inside the loop it will have no effect on the loop itself. You can 
change the value of varnm within the loop. This lets you terminate a FOR-NEXT 
loop before the end value is reached: set varnm to the end value (exprnm,), and 
on the next pass the loop will terminate itself. Do not start the loop outside a 
subroutine and terminate it inside the subroutine. 

FOR-NEXT loops may be nested. Each nested loop must have a different varnm 
variable name. Each nested loop must be wholly contained within the next outer 
loop; at most, the loops can end at the same point. Integer BASIC allows 16 levels 
of FOR-NEXT nesting, Applesoft just 10. 

FOR may be used in immediate mode only in Applesoft. The entire loop must 
be entered on one line. If NEXT is not present, the loop will execute once. 


FP 
Places the Apple Il іп Applesoft. 


Format: 


FP [Dn] [Sn] L Vn] 


The source of Applesoft depends on what kind of Apple Il you have, and what 
options are installed: 


1. With an Apple Il Plus the language is in read-only memory (ROM), no 
matter what options may also exist. 


2. If you have the Applesoft firmware card installed, FP obtains the 
language from it regardless of the switch setting on the card. 


3. With the Apple Language System installed, FP takes Applesoft from it. 
4. On any other Apple Il, FP looks for Applesoft on the specified (or current) 
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disk. If it does not exist there, the message LANGUAGE NOT AVAILABLE 
is displayed. 


FP erases any BASIC program currently in memory. 

If the file does not exist on drive Ол of slot Sn, the FILE NOT FOUND error 
message is displayed. If the disk in drive Ол of slot Sn is not volume Vn, the 
VOLUME MISMATCH error results. 

Ол, Sn, апа Ул сап be specified in any order. If Dn or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Vn is absent. Also, n can be absent; 
DO, SO, or VO will be used. 

Use only in immediate mode. 


GET 


This Applesoft statement accepts a single character from the keyboard without 
echoing it to the screen. 


Format: 
GET var 


Execution pauses until a key is depressed. When var is a string variable, the 
character entered is assigned to that variable. If Ста.-@ is entered, the null string is 
assigned to the variable. 

GET is not often used with a numeric variable for var. When it is, entry of one 
of the digits O through 9 assigns that value to the variable. Entry of a plus sign, 
minus sign, comma, colon, CrRL-G, space, E, or period assigns a value of zero to 
the variable. Entering any character other than those just listed results in the 
message ?SYNTAX ERROR, and the program stops. 

GET cannot be used in direct mode. 

Not available in Integer BASIC. 


GOSUB 


Causes the program to branch to the indicated line. When a RETURN statement is 
executed the program branches back to the instruction immediately following the 
GOSUB. 


General Format: 
GOSUB //ле 


The GOSUB statement calls a subroutine. The subroutine's entry point must 
occur on line number //ле. А subroutine's entry point is the beginning of the 
subroutine in a logical sense. That is to say, it is the line containing the statement 
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(or statements) which are executed first. The entry point need not necessarily be 
the subroutine line with the smallest line number. 

Upon completing execution the subroutine branches back to the line following 
the GOSUB statement. The subroutine uses a RETURN statement in order to 
branch back in this fashion. 

A GOSUB statement may occur anywhere in a program; in consequence a 
subroutine may be called from anywhere in the program. 

Subroutines may be nested; that is to say, subroutines may be called from 
within subroutines. Twenty-five levels of nesting are allowed in Applesoft; that 
means 24 GOSUB statements may be executed before the first RETURN state- 
ment. The limit in Integer BASIC is 16 GOSUB statements. 

Normally you must exit from a subroutine with a RETURN statement, not with a 
GOTO statement. But, you can use a GOTO statement to branch out of a 
subroutine if you first execute a POP statement. 

Cannot be used in immediate mode in Integer BASIC. 


Additional Integer BASIC Format: 
GOSUB exprnm 


In Integer BASIC a numeric expression is allowed in place of the line number. If 
exprnm does not evaluate to an existing line number, the message *** BAD 
BRANCH ERR is displayed. This form of GOSUB enables you to simulate the ON- 
GOSUB instruction, which is not available in Integer BASIC. 


GOTO 


Unconditionally causes program execution to branch to the line indicated. 


General Format: 
GOTO /ine 


Program execution immediately continues with the first instruction in the line 
number indicated. If the line number does not exist the message ?UNDEF'D 
STATEMENT ERROR is displayed by Applesoft; the message *** BAD BRANCH 
ERR is displayed by Integer BASIC. 


Additional Integer BASIC Format: 
GOTO exprnm 


In Integer BASIC a numeric expression is allowed in place of the line number. If 
exprnm does not evaluate to an existing line number the message *** BAD 
BRANCH ERR is displayed. This form of computed GOTO enables you to simulate 
the ON-GOTO statement, which is not available in Integer BASIC. 
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GR 


Converts the screen to low-resolution graphics mode (40 X 40), leaving four 
lines for text at the bottom of the screen. 


Format GR 


The graphics portion of the screen is cleared to black, the cursor is moved to the 
text window, and COLOR is set to O (black). 

If executed while HGR is in effect, GR behaves normally. However if HGR2 is in 
effect, you will be left looking at page 2 of low-resolution graphics and text. This 
can be confusing, as the screen will usually be filled with garbage and nothing you 
type will appear on the screen. To return to normal mode, type TEXT. Be sure to 
use TEXT in your programs before switching from HGR2 to GR. 

You can switch to full-screen (40 X 48), low-resolution graphics with the 
statement POKE - 16302,0 after executing GR. Anything you subsequently type 
in immediate mode will show up as color dots on the last four lines of the display 
screen, but will execute properly. POKE —16302,0 restores the text window. 


HCOLOR- 


This Applesoft statement sets the color for plotting in high-resolution graphics 
mode. 


Format: HCOLOR= exprnm 


Until the next HCOLOR statement, all HPLOT and DRAW statements will be 
executed in the color specified. The color codes are listed in Table 8-3. The value 
of exprnm must be in the range O through 7. Values outside this range will pro- 
duce an 7ILLEGAL QUANTITY ERROR message. A high-resolution graphics plot 
executed before the first HCOLOR statement will be in an indeterminate color. 
HCOLOR does not affect low-resolution graphics. An HCOLOR statement that 


TABLE 8-3. High-Resolution Color Codes 


Violet* 
White 


* Depends on TV control settings 
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is executed while the Apple Il is not in high-resolution graphics mode does not 
affect the color of the next high-resolution graphics plot. 
Not available in Integer BASIC. 


HGR 


This Applesoft statement converts the screen to high-resolution graphics mode 
(280 X 160), with a four-line text window at the bottom. 


Format: HGR 


Page 1 of high-resolution screen memory is displayed. The low-resolution (text) 
screen memory is unaffected, but only the lowest four lines are visible. The cursor 
is not moved into this four-line text window. You might not be able to see it until 
you have typed several lines after executing HGR. The graphics portion of the 
screen is cleared to black. HCOLOR is left unchanged by this command. 

You can switch to full-screen (280 X 192), high-resolution graphics with the 
statement POKE —16302,0 after executing HGR. Any immediate mode com- 
mands you enter subsequently will not be visible but will still execute properly. 
POKE – 16301,0 restores the text window. 

On Apple ІІ systems with less than 32K bytes of memory, you cannot use HGR 
and the Disk Operating System (DOS) at the same time since they will try to use 
the same area of memory. 

Furthermore, the Applesoft interpreter from disk or cassette occupies part of 
high-resolution graphics page 1 memory. Thus you cannot use HGR with disk- 
based or cassette-based Applesoft. 

Even with firmware Applesoft, if your program is extremely long it might 
extend into high-resolution page 1. You can guard against this with the command 
HIMEM: 8192 which keeps your program out of page 1. 

Not available in Integer BASIC. 


HGR2 


Converts the screen to full-screen, high-resolution graphics mode (280 х 192). 
Page 2 of high-resolution screen memory is displayed. 


Format: 
HGR2 


The low-resolution (text) screen memory is unaffected. Although you cannot see 
what you type, any command that you enter will be executed. The screen is 
cleared to black. HCOLOR is not affected by this command. 

Page 2 of screen memory is not available if your system has less than 24K of 
memory. On 24K systems, set HIMEM: to 16384 before you use HGR2 to protect 
your program and variables from your graphics, and vice versa. 
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You cannot use HGR2 and the Disk Operating System concurrently unless your 
system has at least 36K bytes of memory. That means you need at least 36K to 
use HGR2 in disk-based Applesoft. 

Do not try to establish a text window with POKE — 16301,0. This will display 
low-resolution graphics page 2 while your immediate mode commands go into 
page 1 and hence are invisible (although they execute correctly). 

Not available in Integer BASIC. 


HIMEM: 


Sets an upper boundary on memory available to BASIC programs, including varia- 
ble storage. 


Format: 
HIMEM: exprnm 


HIMEM: establishes the highest location in read/write memory (RAM) available to 
your BASIC program. The Disk Operating System (DOS) always resides above 
HIMEM: if it is present. With the HIMEM: statement you can set aside additional 
space for machine language subroutines and high-resolution graphics shape 
tables. You can also protect the high-resolution graphics screen memory area of 
RAM. 

HIMEM: is first set to the highest memory location on your Apple Il (e.g., 49151 
оп a 48K Apple 1). DOS resides in the highest part of memory, so it adjusts 
HIMEM: downward approximately 10,800 bytes when it is booted. Each addi- 
tional file buffer you reserve via MAXFILES lowers HIMEM: another 595 bytes. If 
your Applesoft program uses strings, their values are stored starting at the result- 
ing location of HIMEM:, working downwards. Refer to the memory map in Appen- 
dix G. 

The value of exprnm must be in the range -65535 through 65535 (-32767 
through 32767 in Integer BASIC) or an error message occurs. 

You should not set HIMEM: higher than the maximum memory location availa- 
ble. If you do, some of your variable storage might end up in nonexistent memory. 

You can see the current value of HIMEM: by using the appropriate instruction 
shown below: 


PRINT PEEK(116) « 256 + PEEK(115) for Applesoft 
PRINT PEEK(77) * 256 + РЕЕК(76) for Integer BASIC 


HIMEM: is not affected by NEW, RUN, or CLEAR. 

If you set HIMEM: lower than LOMEM:, or do not leave enough memory to run 
your program, an error message occurs. 

Can only be used in immediate mode in Integer BASIC. 
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HLIN 


Draws a horizontal line on the screen in low-resolution graphics mode. 


Format: 
HLIN co/,, col; AT row 


The line is drawn from co/, to col, in the row specified. The color is determined by 
by the COLOR statement last executed. If the screen is in text mode, or the text 
window is present and rowis greater than 39, HLIN will draw a line of characters 
on the screen in the text window where the graphics dots would be plotted. The 
characters used are determined by previously executed COLOR statements; see 
Table 8-5 (near the PLOT statement in this chapter) for particulars. 

In integer BASIC, co/, must be less than or equal to co/; ог the message 
+++ RANGE ERR is displayed. 


HOME 


This Applesoft statement clears the display screen and postions the cursor to the 
upper lefthand corner (row 1 and column 1). 


Format: 
HOME 
In Integer BASIC, use CALL —936. 


HPLOT 


This Applesoft statement places a dot or draws a line of color on the high-resolu- 
tion graphics screen. 


Formats: 


HPLOT со/һ, rowh 
HPLOT TO colh, rowh 
HPLOT co/h,, rowh, TO col,, rowh, (ТО colh;, rowh,...] 


The first form of the command places a dot of color on the screen at the specified 
location. The color of the dot is determined by the HCOLOR statement last 
executed. 

The second form of the command draws a line of color from the last dot plot- 
ted to the coordinates со/һ and rowh. If there has been no dot plotted since the 
last HGR or HGR2 command, nothing will be plotted. The color of the line is deter- 
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mined by the HCOLOR statement last executed. 

The third form of the command also draws a line of color. With firmware 
Applesoft, the line may have more than one segment. The line is first drawn from 
colh, and rowh, to colh, and rowh,. The color of the line (all segments) is deter- 
mined by the HCOLOR statement last executed. 

Additional coordinates are not allowed in cassette- or disk-based Applesoft. 
When present in a firmware Applesoft program, a new line segment is then drawn 
from colh, and rowh, to colh, and rowh;, and so on. There can be any number of 
coordinate pairs, as long as they all fit on one program line. 

Any portion of a line or dot that lies within the text window will not be visible. 
However, if you switch to full-screen graphics with the command POKE 
—16302,0 any line or point plotted in the text window will then be visible. 

You must always execute an HGR or HGR2 statement before an HPLOT. Other- 
wise you may destroy your program or variables. 

Not available in Integer BASIC. 


HTAB 


This Applesoft statement positions the cursor to the specified column on the cur- 
rent display line. 


Format: 
HTAB со/ 


The cursor moves right or left to the column specified by the value of co/, without 
erasing any displayed characters. Columns are numbered from 1 to 40 (left to 
right). 

In Integer BASIC, use the TAB statement. 


IF-THEN 


Conditionally causes the program to execute the indicated instruction or instruc- 
tions. The rules for Integer BASIC and Applesoft are presented separately. 


Integer BASIC Formats: 


IF expr THEN statement 
IF expr THEN [GOTO] //ле 


In the first form of the IF-THEN statement, the expression specifies a condition 
which, if true, causes the statement following the THEN to be executed. If the 
condition is false, the statement immediately following the IF-THEN statement is 
executed; the statement that follows THEN is not executed in this case. 

In the second format of the IF-THEN statement (the conditional branch format), 
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the expression specifies a condition which, if true, causes the program to branch 
to the indicated line number. 

Relational expressions are the most common type of expression used with IF- 
THEN. String values can only be compared for equality or nonequality in Integer 
BASIC. 

expr can also be a numeric expression. In this case, expr is considered true if it 
has a nonzero value. 

The IF-THEN expression cannot be a string expression (i.e., anything that evalu- 
ates to a string value) in Integer BASIC. 


Applesoft Formats: 


IF expr THEN statement [:statement. . ] 


THEN 
IF expr GOTO line 
THEN GOTO 


In the first format of the IF-THEN statement, the expression specifies a condition 
which, if true, causes every statement that follows THEN on the same program 
line to be executed. If the specified condition is false, control passes to the first 
statement on the next program line and any statements following the THEN are 
not executed. 

In the second format (the conditional branch format), the program branches to 
line number //ne if the condition is true. Otherwise execution continues with the 
first statement on the next program line after the IF- THEN. 

If an unconditional branch is one of many statements following THEN, then the 
branch must be the last statement on the line, and it must have the GOTO //ле Ғог- 
mat. If the unconditional branch is not the last statement on the line, then state- 
ments following the unconditional branch can never be executed. 

The most common type of expression used with IF- THEN is a relational expres- 
sion. If string expressions are compared using relational operators, the ASCII 
codes (listed in Appendix 1) for the characters involved determine the relative 
values of the strings. Strings are compared character by character until a 
mismatch occurs. Then the string with the higher ASCII code in the mismatch 
position is considered greater. If no mismatch occurs, the longer string is greater. 

The expression may also be a numeric expression. If the value of the expres- 
sion is not zero, the condition is considered true. If the value of the expression is 
zero (false), execution continues at the first statement on the next higher program 
line. 

In Applesoft, expr may also be a string expression. However, execution of more 
than two or three of such IF- THEN statements in the course of a program gene- 
rates the message 7FORMULA TOO COMPLEX ERROR. 

Applesoft has problems if the last nonspace character preceding THEN is the 
letter A. The A is combined with the T to form the reserved word AT. You can 
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avoid this problem by enclosing some or all of the expression (including the trou- 
blesome A) in parentheses. 

If a FOR-NEXT loop follows the THEN, then the loop must be completely con- 
tained on the IF- THEN line. Additional IF-THEN statements may appear following 
the THEN as long as they are completely contained on the original IF-THEN line. 
However, a Boolean expression beats nested IF-THEN statements for clarity. For 
example, the two statements below are equivalent, but the second is easier to 
read. 

10 IF A$ = "X" THEN IF B = 2 THEN IF C > D THEN 50 
10 IF A$ = “X” AND B = 2 AND C > D THEN 50 


ІМЗЕ 


Selects the peripheral slot from which subsequent input will be accepted. 


Format: 
ІМЗЕ slot 


Subsequent INPUT statements will look for data from the peripheral in the slot 
indicated. s/ot must be an integer constant between O and 7. Note that slot O is 
not a peripheral device; ІМЗЕ O specifies the keyboard as the input device. If there 
is no peripheral іп the specified slot the system will lock up until you press Reser. 

Whenever DOS is present in the Apple ІІ memory, І№ is considered a DOS 
command, requiring PRINT and Ста. -О in programmed mode. 


INIT 


Initializes a disk. 


Format: 
INIT filename [Dn] [Sa] [Vn] 


The program currently in memory is saved on the disk under the file name given. 
This program becomes the greeting program, and is run automatically whenever 
this disk is booted. The disk is assigned the volume number it is initialized with; if 
no volume number is specified, the disk is assigned the default volume number of 
254. 

If the file does not exist on drive Ол of slot Sn, the FILE NOT FOUND error 
message is displayed. 

Ол, Sn, and Vn can be specified іп any order. If Ол or Sn is omitted, the last- 
referenced drive or slot is used. Also, n сап be absent; DO or SO will be used. 

INIT may only be used in immediate mode. 
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INPUT 


Accepts character entry from the keyboard or other input device, evaluates it, and 
assigns the value or values entered to the variable or variables specified. 


Integer BASIC Format: 
INPUT [" prompt") var var... 11 


INPUT in Integer BASIC requests values for any combination of integer and string 
variables. If the first variable is an integer, then a question mark is displayed at the 
current cursor location as a cue to begin entry. Integer BASIC suppresses the 
question mark if a string is the first variable to receive input. 

The optional prompt is a string constant. If it is present, it will be displayed just 
before the first variable is input; it is not repeated for each variable in the list. A 
question mark is displayed after the prompt if an integer variable is to be entered. 
The prompt alone is displayed if a string variable is to be entered. Note that the 
promptis followed by a comma in the INPUT statement. The prompt may not be a 
string variable or string expression. 

When a single INPUT statement calls for more than one integer value in suc- 
cession, you can enter each one on a separate line; end each value with the 
Return key. Integer BASIC displays a double question mark (? ?) on each new line 
as a cue to continue entries for the INPUT statement. Optionally, you can enter 
more than one integer value on a single line; separate the values with commas. 

Numeric input must consist only of valid numeric characters. These are the 
digits O through 9, spaces, and a plus or minus sign. You get an error message if 
you simply press Return when a numeric value is to be entered. 

You must enter each string value on a separate line. All characters (except 
CrRL-C апа Стяь-Х) that you enter prior to pressing the Return key are accepted 
and assigned to the string variables. The null string ("''") is assigned to the variable 
if you simply press Нетуям when a string value is to be entered. 

If you enter unacceptable characters (e.g., letters in a numeric value) the warn- 
ing message *** SYNTAX ERR and RETYPE LINE appear. You must reenter all 
values that you entered on the offending line. 

May not be used in immediate mode. 


Applesoft Format: 
INPUT ["prompt'';) varL,var. . .] 

INPUT can request values for any combination of numeric and string variables. A 
question mark is normally displayed as a cue to begin entry at the current cursor 
location. Applesoft suppresses the question mark if the optional prompt is pre- 
sent. 

The optional prompt is a string constant. If it is present, it will be displayed just 
before the first variable is input; it is not repeated for each variable in the list. No 
question mark is displayed after the prompt. Note that the promptis followed by a 
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semicolon in the INPUT statement. 

Generally speaking, when a single INPUT statement calls for more than one 
value, you can enter each one on a separate line; end each value with the RETURN 
key. Optionally, you can enter more than one value on a single line; separate the 
values with commas. 

If you enter unacceptable characters (e.g., letters in a numeric value) a warning 
message appears and you must completely reenter the value. Applesoft displays 
REENTER and reexecutes the INPUT statement from the beginning. The cue 
(question mark or prompt) is redisplayed and you must reenter all values for the 
INPUT statement. 

Numeric input must consist only of valid numeric characters. If you simply 
press Return when a numeric variable is to be entered, you receive an error 
message and must reenter the line. The digits O through 9, spaces, and a plus or 
minus sign are accepted as numeric input. Applesoft also accepts a decimal point, 
an additional plus or minus sign, and the letter E for entering real values and scien- 
tific notation. 

In Applesoft, if the first nonspace character of a string entry is a quotation 
mark, all characters (including commas and colons) up to the next quotation mark 
or Return are assigned to the string variable. If the entry does not begin with a 
quotation mark, all characters (including quotation marks) up to the next comma, 
colon, or Return are assigned to the variable. If two or more strings are requested 
by the same INPUT statement, they must be enclosed in quotes and separated by 
commas. 

If you simply press REruRN when a string variable is їо be entered, the null string 
("') is assigned to the variable. 

In Applesoft, all characters after a colon in an INPUT response are ignored 
unless the entry begins with a quotation mark. 

INPUT cannot be used in direct mode. 


INT 
Places the Apple Il in Integer BASIC. 


Format: INT 


Any program currently in memory is erased. If Integer BASIC is not present (e.g., 
on an Apple Il Plus without a Language System), the message LANGUAGE МОТ 
AVAILABLE is displayed. 

Use only in immediate mode. 


INVERSE 


This Applesoft statement turns on inverse video mode (also called reverse video 
mode). 
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Format: 
INVERSE 


All output from subsequently executed PRINT statements will appear as black-on- 
white characters. Error messages are similarly affected. However, characters 
echoed to the screen by INPUT statements are unaffected, as are any previously 
displayed characters. 

INVERSE works by slightly altering the standard ASCII codes. Therefore any 
characters sent to the disk in inverse mode will be saved with incorrect codes. 
When read back in, the wrong characters will result. 

Not available in Integer BASIC. 


LET= 


The assignment statement, LET=, or simply =, assigns a value to a specified 
variable. 


Format: 
[LET] var =expr 


Variable var is assigned the value computed by evaluating expr. 


LIST 


Displays all or part of the program currently in memory. There are two formats for 
the LIST command. One is recognized by both Integer BASIC and Applesoft, the 
other only by Applesoft. They are described separately below. 


General Format: 
LIST /ine, (/іпе:1 


Any portion of the program may be listed. If no line numbers follow LIST, the 
entire program is displayed. If only /ine, is present, only that line will be displayed 
if it exists. If both line numbers are present, the program will be listed starting at 
line, and continuing through //ле;. 

If /ine, does not exist, the listing starts at the next higher line number. If /ine, 
does not exist, the listing ends at the next lower line number. 

LIST may not be used with variables or expressions in place of the line num- 
bers. 

When LIST displays your program it adds extra spaces around variables and 
reserved words to make the listing more readable. If this causes a problem, you 
can eliminate the spaces by reducing the text window to a width of 33 (or less) 
with the command POKE 33,33. (POKE 33,40 restores the text window to full 
width.) 
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Program line lengths are limited but these limits are calculated before LIST 
adds the extra spaces. You can therefore extend the apparent length of your pro- 
gram lines by leaving out spaces when you type the lines in. However, such a line 
will be too long to edit or copy after it has been listed with all the spaces put in. 


Expanded (Applesoft) Format: 


{ line, 1] 


ine, t1 line, 


LIST 


In Applesoft, either a comma (,) or a hyphen (-) may separate the two line num- 
bers. 

In Applesoft you can list from the start of the program to a specific line number 
by putting a comma or hyphen ahead of /ine, (and omitting /ine,). You can also 
list from a specific line number to the end of the program by putting a comma or 
hyphen after //ле, (and omitting /ine,). 


LOAD 


Loads a program from cassette or disk. 


Cassette Format: 
LOAD 


Loads the next sequential program from the cassette, replacing any program cur- 
rently in memory. You must have the cassette recorder running in PLAY mode 
when LOAD is executed; the Apple ЇЇ does not remind you to do this. The Apple Il 
beeps as it starts to load a program and beeps again when it finishes. The second 
beep is your signal to manually stop the cassette recorder. 

You can only use LOAD in immediate mode in Integer BASIC. 


Disk Format: 
LOAD filename LDn] LSn] L Vn] 


The program with the name filename is loaded from the disk. If the LOAD is suc- 
cessful, any program previously in memory is erased. 

If the program to be loaded is in Applesoft and the Apple Il is currently in 
Integer BASIC, or vice versa, the Apple ll switches to the proper language. This 
may require loading the language from the specified disk. If the language is not 
available, the message LANGUAGE NOT AVAILABLE is displayed. 

If the file does not exist on drive Ол of slot Әл, the FILE NOT FOUND error 
message is displayed. If the disk in drive Ол of slot Әл is not volume Ул, the 
VOLUME MISMATCH error results. 
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Dn, Sn, and Vn can be specified іп any order. If Ол or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Vn is absent. Also, n can be absent; 
DO, SO, or VO will be used. 

This is a DOS command, requiring PRINT and Crri-D in programmed mode. 


LOCK 


Protects a disk file from accidental erasure. 


Format: 
LOCK filename LDn] [Sn] LVn) 


Once locked, a file cannot be deleted or renamed until it is unlocked (see 
UNLOCK). No program can be saved using the name of the locked file. A locked 
file is indicated in the disk catalog by an asterisk at the left of the file type. 

If the file does not exist on drive Ол of slot Sn, the FILE NOT FOUND error 
message is displayed. If the disk in drive Ол of slot Sn is not volume Ул, the 
VOLUME MISMATCH error results. 

Ол, Sn, and Ул can be specified іп any order. If Dn or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Vn is absent. Also, n can be absent; 
DO, SO, or VO will be used. 

This is a DOS command, requiring PRINT and Crat-D in programmed mode. 


LOMEM: 


Sets a lower boundary on memory available to BASIC programs for variable 
storage and the like. 


Format: 
LOMEM: exprnm 


LOMEM: establishes the lowest location in read/write memory (RAM) available for 
your BASIC program lines and variables. The Monitor and the BASIC interpreter 
use read/write memory below LOMEM: for pointers, low-resolution graphics and 
text screen memory, and so forth. When the Applesoft interpreter is loaded from 
disk or cassette it always resides in read/write memory below LOMEM:. You сап 
set aside additional space for machine language subroutines and high-resolution 
graphics shape tables with the LOMEM: statement. 

With Integer BASIC or firmware Applesoft, LOMEM: starts out at memory loca- 
tion 2048, just above the system-use area. Loading the Applesoft interpreter 
from disk or cassette raises LOMEM: to 12291. Each time you add an Applesoft 
program line or change an existing line, LOMEM: is adjusted up or down. Erasing 
an Applesoft program (with NEW or Crrt-B) also changes LOMEM:. So if you 
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want to reserve space below your program, you must do so after erasing any pre- 
vious program but before loading or typing in the new one. 

The value of exprnm must be in the range —65535 through 65535 (-32767 
through 32767 in Integer BASIC), or an error message occurs. 

You can display the current value of LOMEM: with the instruction PRINT 
PEEK(106) * 256 + PEEK(105). 

In Applesoft, if LOMEM: is set higher than the current value of HIMEM:, lower 
than the existing value of LOMEM:, or lower than the highest memory location 
used by the current operating system or program, then the message ?OUT OF 
MEMORY ERROR occurs. 

Can only be used in immediate mode in Integer BASIC. 


MAN 


Ends automatic line numbering mode in Integer BASIC. 


Format: 
MAN 


Automatic line numbering is instituted with AUTO. 

Type CrRL-X to temporarily halt the generation of line numbers, then enter 
MAN. 

Not available in Applesoft. 


MAXFILES 


Specifies the maximum number of disk files that may be active at any one time. 


Format: 
MAXFILES /imit 


The Disk Operating System (DOS) supports an absolute maximum of 16 open 
files at once. When executed, MAXFILES sets aside 595 bytes of memory (a file 
buffer) for each file. MAXFILES is automatically set to 3 when you boot DOS. 

All DOS commands except MAXFILES use a file buffer while they are execut- 
ing. Thus, the practical maximum number of files you may have open at any one 
time is one less than the MAXFILES limit. If you attempt to execute any DOS com- 
mand when there is no buffer free, the error message NO BUFFERS AVAILABLE is 
generated. 

MAXFILES resets НІМЕМ: when executed, which may erase part of your рго- 
gram, variable storage, etc. If possible, execute MAXFILES before you load or run 
your program. 

If you use MAXFILES within an Applesoft program, use it as the first line. To 
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use MAXFILES in an Integer BASIC program, you must create an EXEC file as dis- 
cussed in Chapter 5 (see also EXEC in this chapter). 

limit must be an integer constant in the range 1 through 16 or the RANGE 
ERROR message occurs. 

This is а DOS command, requiring PRINT апа Стя. -О in programmed mode. 


MON 


Causes disk commands and/or data flow to be displayed on the screen. 


Format: 
MON [C] [Л] LO] 


The three parameters dictate what is displayed. If C is specified, all disk com- 
mands are displayed on the screen. If | is specified, all data input to the Apple Il 
from the disk is displayed. If О is specified, all data output from the Apple Il to the 
disk is displayed. These parameters may be used in any combination and in any 
order. If none of them is present, MON has no effect. MON remains in effect until a 
NOMON, FP, or INT is executed, the system is rebooted, or on some machines, 
Reser is struck. 
This is a DOS command, requiring PRINT апа Crat-D in programmed mode. 


NEW 


Deletes the current program and all variables from memory. 


Format: 
NEW 


NEW also resets LOMEM:, but does not affect HIMEM:, COLOR, or HCOLOR. 
NEW may only be used in immediate mode in Integer BASIC. 


NEXT 


Terminates the loop started by a FOR instruction. 


General Format: 
NEXT varnm Í, varnm.. ] 


When NEXT is executed, loop index variable varnm is incremented by an amount 
specified in the corresponding FOR statement. The program then either continues 
with the instruction following NEXT or loops back to the corresponding FOR, 
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depending on the parameters set in the FOR statement. See the discussion of FOR 
earlier in this chapter. 

If there is no currently active FOR loop that matches varnm, an error will occur. 
?NEXT WITHOUT FOR ERROR is displayed by Applesoft; *** BAD NEXT ERR is 
displayed by Integer BASIC. 

Multiple variables following NEXT must be listed in the proper order (the last 
loop initiated must be terminated first) or an error will occur. 

NEXT may not be used in immediate mode in Integer BASIC. In Applesoft, an 
immediate mode NEXT may cause a branch to a FOR that was executed in pro- 
grammed mode and is still active. 


Additional Applesoft Format: 
NEXT 
In Applesoft you may use NEXT with no identifying variable name. The loop varia- 


ble defaults to that of the most recently begun FOR loop that is still in effect. 
NEXT with no variable executes more rapidly than NEXT with a variable. 


NO DSP 
Cancels display mode for the specified variable in Integer BASIC. (See DSP.) 


Format: 
NO DSP var 
Not available in Applesoft. 


NOMON 
Ends the display of disk commands or data flow that was initiated by MON. 


Format: 
NOMON [С] [1] [,0] 


Each parameter specified cancels part of the display started by MON. If C is 
specified, disk commands are not displayed. If | is specified, data input to the 
Apple Il from the disk is not displayed. If O is specified, data output from the Apple 
ll to the disk is not displayed. These parameters may be used in any combination 
and in any order. If MON is not in effect for the parameter or parameters specified, 
or no parameters are specified, NOMON has no effect. 

This is a DOS command, requiring PRINT and CrRL-D in programmed mode. 
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NORMAL 
This Applesoft statement turns off FLASH and INVERSE video modes. 


Format: 
NORMAL 
See FLASH and INVERSE. 
Not available in Integer BASIC. 


NO TRACE 


Turns off the tracing of program execution that was initiated by TRACE. 


Format: 
NO TRACE 


If TRACE is not in effect, NO TRACE has no effect. 


ONERR GOTO 


Branches to the line number indicated when a subsequent error occurs in an 
Applesoft program. 


Format: 
ONERR GOTO /ine 


This command sets a flag that causes the program to branch to the line number 
indicated when an error occurs. ONERR GOTO must be executed before the error 
occurs. 

Each type of error has a code number. The code of the most recently occurring 
error is stored in memory location 222. PEEK(222) retrieves the error codes. 
The error codes and their messages are listed in Table C-1 (Appendix C). When an 
error occurs inside a FOR-NEXT loop or in a subroutine the pointers and stacks are 
disrupted. Your error-handling routine must return to the FOR or GOSUB state- 
ment, restarting the loop or subroutine. If your error-handling routine returns to a 
NEXT or RETURN statement another error will occur. 

ONERR GOTO will not work properly under some circumstances. The Apple Il 
will lock up if there are two GET errors in a row and the error-handling routine 
ends with RESUME, not GOTO. In programs that use PRINT statements (or if 
TRACE is in effect), the 43rd error not arising from an INPUT statement causes a 
jump to the Monitor. In this situation, if GOTO ends the error-handling routine 
(instead of RESUME), the 87th INPUT error causes a jump to the Monitor. 

You can circumvent all the problems just described if your error-handling 
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TABLE 8-4. Machine Language Fix for ONERR GOTO 


MACHINE LANGUAGE 6502 ASSEMBLY LANGUAGE 
L771L777II77 Гонты 


Put top byte of stack in 
Accumulator 

and save it in Y index register 

Put next byte of stack in 
Accumulator 

Use ONERR pointer 


as stack address 

Push saved stack contents on 
‘ONERR’ stack (two bytes — 
from Accumulator and Y 
register) 

Return to Applesoft 


routine includes a call to the machine language program in Table 8-4. 

Use the POKE statement to put the decimal numbers into memory locations 
768 through 777 (or any available memory locations). Then CALL 768 from your 
error-handling routine. 

Not available in Integer BASIC. 

Cannot be used in immediate mode. 


ON-GOSUB 


Provides conditional subroutine calls to one of several subroutines in an Applesoft 
program, depending on the current value of an expression. 


Format: 
ON exprnm GOTO line [,/ine . . .] 


The program branches to the first line number if the integer value of the expres- 
sion is 1, the second if it is 2, etc. The next RETURN statement encountered sends 
the program back to the statement following the ON-GOSUB. 

The expression must have a value in the range O through 255 or the message 
?ILLEGAL QUANTITY ERROR occurs. If the expression evaluates to zero or to а 
value greater than the number of line numbers listed, program execution con- 
tinues with the next instruction following the ON-GOSUB. 

Not available in Integer BASIC. (But see GOSUB for an Integer BASIC form of 
computed GOSUB.) 
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ON-GOTO 


Causes a conditional branch to one of several points in an Applesoft program, 
depending on the current value of an expression. 


Format: 
ON exprnm GOTO fine Lline. . ] 


The program branches to the first line number if the integer value of the expres- 
sion is 1, the second if it is 2, etc. 

The expression must have a numeric value in the range O through 255 or the 
message 7ILLEGAL QUANTITY ERROR occurs. If the expression evaluates to zero 
or to a value greater than the number of line numbers listed, program execution 
continues with the next instruction following the ON-GOTO. 

Not available in Integer BASIC. (But see GOTO for an Integer BASIC form of 
computed GOTO.) 


OPEN 


Prepares a sequential or random-access disk text file for accessing. 


Format: 
OPEN filename [Алп] [Dn] LSn] [Мл] 


A memory buffer of 595 bytes is allocated to the text file specified. The READ 
and WRITE commands can now be used with the file to retrieve and store infor- 
mation. If the file specified is not on the disk, one is created. If the file is already 
open, it is closed and then reopened. 

If the L parameter is not specified, the file is opened as a sequential file. 

If the L parameter is specified, the file is opened as a random-access file. The 
number n following L is the record length in bytes and must be an integer constant 
in the range 1 through 32767. It can be absent; L1 is used. Each time that a par- 
ticular random-access file is opened, the record length must be the same. 

If the disk in drive Dn of slot Sn is not volume Ул, the VOLUME MISMATCH 
error results. 

Ол, Sn, and Ул can be specified in any order. If Ол or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Vn is absent. Also, n can be absent; 
DO, SO, or VO will be used. 

This is a DOS command, requiring PRINT and CrnL.-D in programmed mode. 

OPEN may not be used in immediate mode. 


PDL 


Listed in the Functions section of this chapter. 
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PEEK 


Listed in the Functions section of this chapter. 


PLOT 


Displays a point on the low-resolution graphics screen. 


Format: 
PLOT со/, row 

In low-resolution graphics mode, PLOT places a dot of color on the screen. The 
color of the dot is determined by the COLOR statement last executed. Column 
numbers range between O and 39. Column O is at the left edge of the screen; col- 
umn 39 is at the right. Row numbers range between O and 47. Row O is at the top 
of the screen; row 47 is at the bottom. A point plotted in rows 40 through 47 will 
be in the four-line text window unless a POKE —16302,0 has been executed to 
eliminate the text window. 

In text mode or in the text window PLOT places a colored character, rather than 
a dot, on the screen. Since a character occupies the space of two vertically 
stacked graphics dots, there are two different sets of PLOT coordinates that will 
cause some character to appear in a given location. To place a particular character 
on the screen, you must PLOT both halves of the character location. The 
character that appears is determined by the COLOR statement last executed 
before each half is plotted. 

Table 8-5 shows the characters generated by each combination of colors in 
the upper and lower graphics points. To generate a particular character, find it in 
Table 8-5; read up and left to find the colors that you must PLOT in each half of 
the character. The upper half of a character is specified by a PLOT in an even row, 
the lower half by a PLOT in an odd row. If you only plot one half of a character 
location, the character generated is based on the color of the PLOT and the color 
already present in the other graphics point. 


TABLE 8-5. Characters Generated by Graphics Statements in Text Mode 
COLOR OF UPPER GRAPHICS POINT 
For For 
Inverse Flashing | For Norma! 
Video Character | Character |0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 
DODBDDEDDDUE 
ВЕВВЕВЕВВЕ 


GRAPHICS 
POINT 


of «fe 
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Note that each character can be generated by four different colors for the 
lower graphics point. They are not all identical, however. The character will be in 
reverse video if the color number of the lower point is less than 4, it will be flash- 
ing if the number is in the range 4 through 7, and it will be normal if the number is 
in the range 8 through 15. 


POKE 


The POKE statement stores a byte of data in a specified memory location. 


Format: 
POKE memaar, byte 


A value between O and 255, provided by byte, is written into memory at location 
memadr. |f the memory location specified exceeds the maximum location in 
memory (e.g., 16383 if you have 16K of memory), or accesses an output device 
that is not receiving, POKE has no effect. 

Use caution with POKE. Some memory locations contain information essential 
to the Apple ІГ5 uninterrupted operation. Change random memory locations and 
you can destroy your program, lock up your system, or clobber your BASIC. 


POP 


Causes the Apple |І to forget the return location for the most recently executed 
GOSUB statement. 


Format: POP 

POP effectively changes the most recently executed GOSUB statement into a 
GOTO statement (ex post facto). The next RETURN statement executed will 
branch to the instruction immediately following the second most recently 
executed GOSUB. If the total number of POP and RETURN statements executed 
in a program exceeds the number of GOSUB statements executed, an error 
message occurs. 


POSITION 


Moves the disk file pointer the specified number of fields ahead of its current 
position. 


Format: 
POSITION filename [,Вл] 
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If the file is not open when POSITION is executed, it is opened (see OPEN). The R 
parameter specifies how many fields the file pointer moves forward from its cur- 
rent position. The number following R must be an integer constant in the range O 
through 32767. If absent, this parameter defaults to zero, i.e., the file pointer is 
not moved. If the file is opened by POSITION, the fields are counted from the 
beginning of the file. The file must be a sequential file. 

A field consists of a sequence of characters ending with a carriage return. 
POSITION goes through the file, character by character, counting such charac- 
ters; the number of carriage return characters encountered is the number of fields 
skipped over. If any unused space is encountered in the file before the specified 
number of fields are counted, the message END OF DATA is given. 

This is a DOS command, requiring PRINT and Crat-D in programmed mode. 

POSITION may not be used in immediate mode. 


РЕ 


Selects the peripheral slot that will receive subsequent output. 


Format: 
PR+ s/ot 


Subsequent PRINT statements will send data to the peripheral in the slot indi- 
cated. s/ot must be an integer constant between О and 7. Note that slot О is not a 
peripheral device. PR# О specifies the standard 40-column display screen as the 
output device. If there is no peripheral in the specified slot the system will lock up 
until you press Reser. 

Whenever DOS is present in the Apple ІІ memory, PR# is considered a DOS 
command, requiring PRINT and CrRL-D in programmed mode. 


PRINT 


Outputs characters to the screen or other output device. 


Format: 
PRINT [expr] LË}. . expr). . Ј 


There are a number of acceptable variations on the PRINT statement. PRINT by 
itself outputs a carriage return and line feed. When PRINT is followed by one or 
more expressions, the values of these expressions are printed. The way the values 
appear depends on their nature and on the use of semicolons or commas in be- 
tween values. 

All numeric values in Integer BASIC and many in Applesoft are displayed using 
standard numeric representation. Negative values are preceded by a minus sign; 
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positive values are not preceded by a sign or a blank space. Scientific notation is 
used in Applesoft for values closer to zero than +.01 and for any values with 
more than nine digits in front of the decimal point. 

String values are displayed just as they are. 

Commas and semicolons determine the spacing between printed values. A 
semicolon causes the next value to print immediately after the value just printed; 
they are concatenated with no intervening spaces. А comma causes the next 
value to print at the next tab stop, several spaces over from the last value. 

In Integer BASIC, tab stops are eight characters apart, at columns 1, 9, 17, and 
so on. If any nonblank character is printed in the space just ahead of a tab stop 
(e.g., in column 16), that tab stop is inactivated. 

Applesoft places tab stops 16 characters apart, at columns 1, 17, 33, and so 
on. Tab stops on the display screen will be inactivated according to a scheme 
illustrated in Figure 4-1 (Chapter 4). For other devices, a tab stop is inactivated if a 
nonblank character is printed just ahead of it (e.g., in column 32). 

If the list of expressions does not end with a comma or semicolon, a carriage 
return and line feed are printed following the last item in the list. If the list ends 
with a semicolon the first character printed by the next PRINT statement will print 
directly following the last character printed by the current PRINT statement, with 
no intervening spaces. If the list ends with a comma the next output will print 
starting in the first position of the next tab field. 

In Integer BASIC, all items must be separated by either a comma or a semi- 
colon. In Applesoft, items may be listed with no intervening commas or semi- 
colons. Output for such items is concatenated as if the items were separated by 
semicolons. 

Applesoft recognizes a question mark (?) as an abbreviation for PRINT. The 
word PRINT will be spelled out when the program is listed, though. 


READ (DISK STATEMENT) 


Specifies a disk file from which subsequent INPUT and GET commands will 
obtain data. 


Format: 
READ filename [,Rn] [Bn] 


IF the file specified is not already open, it is opened (see OPEN). All INPUT and 
GET statements receive characters from the disk until a disk statement (or a CTRL- 
D character (ASCII code 4) alone) is printed, Reset is struck, or an error occurs. If 
the file is not on the disk, the message FILE NOT FOUND appears. 

The file will be read as a sequential file if the R parameter is absent. In a sequen- 
tial file, the B parameter specifies at which byte (character) the READ begins. If 
there is no B parameter, READ begins at the first byte in the file (byte O). If the 
byte to be read was never stored on the disk by a WRITE command, the END OF 
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DATA message is displayed when INPUT or GET is subsequently executed. 

If the R parameter is present, the file will be accessed as a random-access file. 
The R parameter specifies which record of a random-access file will be READ. 

іп a random-access file, the B parameter specifies at which byte within the 
specified record the read begins. If there is no B parameter, READ begins at the 
first byte in the record (byte 0). If the byte to be read was never stored on the disk 
by a WRITE command, the END OF DATA message is displayed when INPUT or 
GET is subsequently executed. 

The numbers following B and R must be integer constants in the range O 
through 32767. If unspecified, zero is assumed. 

Do not use Crat-C to stop a READ statement іп Applesoft. This causes a series 
of ?REENTER messages to be displayed. Use only Reser to stop the program. 

This is a DOS command, requiring PRINT and Ctat-D in programmed mode. 

May not be used in immediate mode. 


READ (ASSIGNMENT STATEMENT) 


Assigns values from Applesoft DATA statements to variables. 


Format: 

READ var [, var. . .] 
There is a pointer to the DATA list which determines which value to assign to the 
first variable in the READ statement. At the start of the program and after a 
RESTORE statement, the pointer points to the first DATA value. As each READ 
statement variable gets a value, the pointer moves ahead to the next value. 

The variables may be of any type, but must match the type of the correspond- 
ing DATA list values. A numeric value assigned to a string variable causes no 
problem. А string assigned to a numeric variable causes the message ? SYNTAX 
ERROR to be displayed. The line number of the offending DATA statement is 
announced with the error message. 

If READ attempts to assign more variables than there are DATA values, the 
?OUT OF DATA ERROR message appears, with the line number of the offending 
READ statement. 

READ may be executed in immediate mode as long as the program in memory 
contains enough DATA values. Otherwise, the message ?ОУТ OF DATA ERROR 
occurs. If the Disk Operating System is present, a READ in immediate mode is 
interpreted as a DOS command, and the message NOT DIRECT COMMAND is dis- 
played. 

Not available in Integer BASIC. 


RECALL 


Retrieves an Applesoft numeric array from cassette tape. 
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Format: 
RECALL varnm 


Applesoft waits indefinitely until the array is found on the tape; no other instruc- 
tion can be executed in the meantime. RECALL does not control tape movement 
nor does it advise when to start the cassette recorder in PLAY mode. There should 
be PRINT statements before and after RECALL which produce advisories. The 
Apple ІІ does beep when it starts getting array values, and beeps again when it 
stops. The array must be dimensioned before the RECALL statement is executed, 
or the message ?OUT OF DATA ERROR is generated (see DIM). 

You need not use the same array variable name in the RECALL statement as 
was used in the STORE statement for the same values. You should use an array 
with the same dimensions as the one that was stored, however. If the array that 
was stored contains more elements than the recalled array, the message ?OUT 
OF DATA ERROR occurs. If the recalled array contains at least as many elements 
as the stored array, but does not have exactly the same dimensions, the message 
ERR is generated, but program execution continues. 

If the recalled array has more elements than the stored array, the values in the 
recalled array will usually be scrambled. There are two exceptions. You may recall 
into an array that has the same number of dimensions as the stored array, where 
each dimension except the last is the same size as the corresponding dimension in 
the stored array. The last dimension may be larger in the recalled array. You may 
also recall into an array with more dimensions than are in the stored array, if the 
dimensions that are in the array match the corresponding dimensions in the 
recalled array (or exceed them, in the case of the last dimension of the stored 
array). 

String arrays cannot be used with RECALL. But recalled numeric values can be 
converted to string values with the CHR$ function. 

Not available in Integer BASIC. 


REM 


The Remark statement (REM) allows comments to be placed in the program for 
program documentation purposes. 


Format: 
REM comment 


comment is any sequence of characters that will fit on the current program line. 
Remark statements are reproduced in program listings, but they are otherwise 
ignored. A REM statement may be placed on a line of its own or it may be placed 
as the last statement of a multiple-statement line. 
REM cannot be placed ahead of any other statements on a multiple-statement 
line, since all text following the REM is treated as a comment. 
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RENAME 


Changes the name of a disk file without altering the file contents. 


Format: 
RENAME filename, filename, LDnlLSn1LVn] 


The file with the name filename, is found on the disk, and its name is changed to 
filename,. the file is open, it is closed (see CLOSE). The file is not affected in any 
other way. 

RENAME will readily change the file name to one that already exists on the 
disk; in fact it will do this any number of times. You must make sure that there is 
no file already named filename, before RENAME is executed. 

If filename, does not exist on drive Ол of slot Sn, the FILE NOT FOUND error 
message is displayed. If the disk in drive Ол of slot Sn is not volume Ул, the 
VOLUME MISMATCH error results. 

Ол, Sn, and Ул can be specified іп any order. If Dn or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Ул is absent. Also, n сап be absent; 
DO, SO, or VO will be used. 

This is а DOS command, requiring PRINT and Crn.-D in programmed mode. 


RESTORE 
Resets the Applesoft DATA list pointer to the beginning of the list. 


Format: 
RESTORE 


Subsequent READ statements start at the first DATA value. 
Not available in Integer BASIC. 


RESUME 


Causes an Applesoft program to resume execution at the beginning of the 
instruction in which an error occurred. 


Format: 
RESUME 
RESUME may only be used after an ONERR GOTO branch has been triggered by 
an error. If RESUME is executed when no error has occurred, the results are 
unpredictable but generally tragic. 
Not available in Integer BASIC. 
Cannot be used in immediate mode. 
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RETURN 


Causes the program to branch to the statement immediately following the most 
recently executed GOSUB. 


Format: RETURN 


The POP statement will obliterate all knowledge of the most recent GOSUB, so 
RETURN after POP causes a branch to the statement following the next most 
recent GOSUB. 

If more RETURN (and POP) than GOSUB statements are executed in a pro- 
gram, an error message occurs. 


ROT- 


This Applesoft statement sets the orientation of high-resolution shapes drawn by 
DRAW or XDRAW. 


Format: ROT=exprnm 


ROT=0 draws the shape in the orientation with which it was defined. The shape is 
rotated 90 degrees clockwise for each increment of 16 in the value of exprnm. 
Thus, ROT=32 draws the shape upside down, and ROT=64 draws the shape in 
its original orientation. Values for exprnm greater than 64 are evaluated modulo 
64. 

When SCALE has been set at 1, there are only four recognized values for 
ROT=. They are O, 16, 32, and 48 (and values greater than 63 equivalent to these 
values). When SCALE=2 there are eight values, when SCALE=3 there are 16 
values, etc., up to a maximum of 64 different recognized values. An unrecognized 
value for ROT= will be treated as if it were the next lower recognized value. 

The exprnm must have a value in the range O through 255 or the message 
?7ILLEGAL QUANTITY ERROR is generated when the ROT= command is 
executed. 

НОТ- is not recognized as a reserved word unless the character ''z'' is the 
first following nonspace character. 

Not available in Integer BASIC. 


RUN (DISK STATEMENT) 


Loads and runs a program from a disk. 


Format: RUN filename [Dn] LSn] L Vn] 
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The program named filename is loaded from the disk and then run. If the load is 
successful, any program previously in memory is erased. 

If the program to be loaded and run is in Integer BASIC and the Apple Il is cur- 
rently in Applesoft, or vice versa, the Apple Il switches to the proper language. If 
necessary, it will load the Applesoft interpreter from the specified disk. If the 
language is not available, the message LANGUAGE NOT AVAILABLE is displayed. 

If the file does not exist on drive Ол of slot Sn, the FILE NOT FOUND error 
message is displayed. If the disk in drive Ол of slot Sn is not volume Ул, the 
VOLUME MISMATCH error results. 

Ол, Sn, and Ул can be specified in any order. If Ол or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Vn is absent. Also, n can be absent; 
DO, SO, or VO will be used. 

This is a DOS command, requiring PRINT and Crat-D in programmed mode. 


RUN (GENERAL STATEMENT) 


Executes the program currently in memory, starting at the specified line number, if 
present; otherwise at the lowest numbered line in the program. 


General Format: 
RUN [Иле] 


If there is no such line number as /ine you will receive the *** BAD BRANCH ERR 
from Integer BASIC or the ?UNDEF'D STATEMENT ERROR from Applesoft. 


Additional Integer BASIC Format: 
RUN exprnm 


In Integer BASIC, the line number can be a numeric expression. 
RUN may only be used in immediate mode in Integer BASIC. 


SAVE 


Saves the program currently in memory on cassette or disk. 


Cassette Format: 
SAVE 


Saves the program currently in memory on cassette tape. You must have the 
cassette recorder running in RECORD mode when SAVE is executed. The Apple Il 
does not remind you to do this. The Apple ІІ beeps as it starts to save a program 
and beeps again when it is finished. The second beep is your signal to manually 
stop the cassette recorder. 
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May only be used in immediate mode in Integer BASIC. 


Disk Format: 
SAVE filename [Оп] LSn] [Мп] 


If there is no file with the name fi/ename on the disk, a file is created with that 
name and in the language of the current program. The program is saved. If there is 
a file named filename in the same language as the current program, the contents 
of that file are erased and the current program is saved in their place. If program 
filename exists but in a different language or with a different file type, the 
message FILE TYPE MISMATCH occurs. 

If the disk in drive Da of slot Sn is not volume Ул, the VOLUME MISMATCH 
error results. 

Ол, Sn, and Vn can be specified іп any order. If Dn or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Vn is absent. Also, n can be absent; 
DO, SO, or VO will be used. 

This is a DOS command, requiring PRINT and CrnL.-D in programmed mode. 


SCALE 


This Applesoft statement sets the size of high-resolution graphics shapes drawn 
by DRAW or XDRAW. 


Format: 
SCALE= exprnm 

The size of the shape in the shape table is multiplied by the integer value of 
exprnm. Thus, if SCALE=1 the shape will be drawn just as it was defined, if 
SCALE=2 it will be drawn twice that size, etc. If SCALE-O the shape is drawn 
255 times the size of the original. 

The value of exprnm must be in the range O through 255 or the message 
?ILLEGAL OUANTITY ERROR occurs when the SCALE command is executed. 

SCALE is not recognized as a reserved word unless the character ''z'' is the 
first following nonspace character. 

Not available in Integer BASIC. 


SHLOAD 


This Applesoft statement loads a high-resolution graphics shape table from 
cassette tape. 


Format: 
SHLOAD 
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Constructing and storing a shape table on cassette tape is discussed in Chapter 6. 

The shape table is loaded into memory just below HIMEM: and HIMEM: is set 
just below the shape table. The starting location of the table is stored in memory 
locations 22 and 23. 

Before you execute SHLOAD be sure that you have set HIMEM: so that the 
shape table will not be loaded on top of your program or variables and will not be 
erased by your graphics. Refer to the discussion of HIMEM: in this chapter, 
memory maps in Appendix G, and to Chapter 6 for more information. 

Not available in Integer BASIC. 


SPEED 


This Applesoft statement changes the rate at which characters are output. 


Format: 
SPEED exprnm 
The value of exprnm establishes the rate at which characters appear on the dis- 
play screen or other output device. Speeds range from O (slowest) to 255 
(fastest). 
Not available in Integer BASIC. 


STOP 
Causes an Applesoft program to halt execution. 


Format: 
STOP 
The Apple Il returns to immediate mode. The message BREAK IN /ine is displayed, 
where /ine is the line number at which the STOP was executed. 
Not available in Integer BASIC. 


STORE 


Saves the specified Applesoft array on cassette tape. 


Format: 

STORE varnm 
STORE does not control tape movement nor does it advise when to start the 
cassette recorder in RECORD mode. You must have the cassette recorder running 
and ready to record when STORE is executed. Your Applesoft program should 
display advisories (via PRINT statements). The Apple ІІ does beep when it starts 
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saving values and beeps again when it stops. 
You may only STORE numeric arrays; string arrays must be converted to 
integer values using the ASC function in order to be stored (see also RECALL). 
Not available in Integer BASIC. 


TAB 


This Integer BASIC statement positions the cursor to the specified column on the 
current display line. 


Format: TAB col 


The cursor moves right or left to the column specified by the value of co/, without 
erasing any displayed characters. Columns are numbered from 1 to 40 (left to 
right). 

For Applesoft, use the HTAB statement. See also the TAB function listed in the 
Functions section of this chapter. 


TEXT 


Returns the screen to the usual full-screen text mode from any of the graphics 
modes. 


Format: 
TEXT 


The prompt and cursor are moved to the last line of the screen; if issued in text 
mode, this is the only result. If the text window has been set to anything other 
than full-screen, TEXT resets to full-screen. 

TEXT does not clear the screen, or more precisely, does not clear page 1 of 
low-resolution screen memory. Since the normal text mode uses the same screen 
memory as low-resolution graphics, executing TEXT while in low-resolution 
graphics mode will leave the top 20 lines of the screen filled with strange charac- 
ters. 


TRACE 


Displays the line number of each statement as it is executed. 


Format: . 
TRACE 
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This debugging aid may cause line numbers to display intermixed with your pro- 
gram's output, rendering one or both illegible. TRACE is only turned off by NO 
TRACE. 


UNLOCK 


Removes locked status from a disk file, permitting it to be changed or deleted. 


Format: 
UNLOCK filename [Dn] Өлі [Ул] 


If the file specified is locked, the lock is removed. If the specified file is not locked, 
nothing happens (see (ОСК). 

If the file does not exist on drive Ол of slot Sn, the FILE NOT FOUND error 
message is displayed. If the disk in drive Ол of slot Sn is not volume Ул, the 
VOLUME MISMATCH error results. 

Ол, Sn, and Vn can be specified in any order. If Dn or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Vn is absent. Also, n can be absent; 
DO, SO, or VO will be used. 

This is a DOS command, requiring PRINT and Crrt-D in programmed mode. 


USR 


Listed іп the Functions section of this chapter. 


VERIFY 


Checks a specified disk file for self-consistency. 


Format: 
VERIFY filename LDn] [Sn] [Vn] 


When a file is saved on a disk with a SAVE, BSAVE, or PRINT statement, a 
checksum is calculated for each sector and stored on the disk. VERIFY recalcu- 
lates these checksums and compares them to the checksums on the disk. If they 
match, the file is intact and no message is returned. If one or more do not match, 
the message 1/О ERROR is generated. Any type of file may be verified. 

If the file does not exist on drive Ол of slot S», the FILE NOT FOUND error 
message is displayed. If the disk in drive Ол of slot Sn is not volume Vn, the 
VOLUME MISMAT CH error results. 

Ол, Sn, and Ул can be specified іп any order. If Dn or Sn is omitted, the last- 
referenced drive or slot is used. VO is used if Vn is absent. Also, n can be absent; 
DO, SO, or VO will be used. 
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This is a DOS command, requiring PRINT and CrnL-D in programmed mode. 


VLIN 


Draws a vertical line on the screen in low-resolution graphics. 


Format: 
VLIN row,, row; AT col 


The line is drawn from row, to row, іп the column specified by co/ The color is 
determined by the COLOR statement last executed. If the screen is in text mode, 
or the text window is present and either row is greater than 39, some or all of the 
line will appear as characters instead of graphics dots. The characters used are 
determined by previously executed COLOR statements; see Table 8-5 (near the 
PLOT statement in this chapter) for particulars. 

In Integer BASIC, row, must be less than or equal to row, or the message 
### RANGE ERR will be displayed. 


VTAB 


Positions the cursor to the specified line in the current display column. 


Format: 
VLIN row 


The cursor moves up or down to the line specified by the value of row, without 
erasing any displayed characters. Rows are numbered from 1 to 24 (top to bot- 
tom). 


WAIT 


Halts an Applesoft program until a particular memory location attains a specified 
condition. 


Format: 
WAIT memadr, exprnm, Lexprnm;] 


WAIT checks all or part of the eight bits of memory location memadr for the pat- 
tern of ones and zeros specified by the binary value of exprnm,. The binary value 
of exprnm, determines which bits of the memory location to consider and which 
to ignore. If a particular bit of exprnm, is 1, then the corresponding bit of memory 
location memadr is checked. Conversely, WAIT ignores those memory bits that 
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correspond to О bits in the binary value of exprnm,. 

As long as the significant bits (as determined by exprnm,) of memadr are all 
different from the corresponding bits of exprnm,, the wait continues. The 
moment any pair of significant bits are the same leither both O or both 1) the wait 
is over and the Applesoft program continues. 

If exprnm, is absent, О is used. 

WAIT can only be interrupted by Reset (or power off). The value of the numeric 
expressions must Бе in the range О through 255 or the message ?ILLEGAL 
QUANTITY ERROR is generated. If the specified memory location is greater than 
the maximum location in memory (e.g., 32767 if you have 32K of memory), or 
accesses an output device that is not receiving, WAIT will lock up the system until 
you press Reset. 

Not available in Integer BASIC. 


WRITE 


Specifies a disk file to which subsequent PRINT statements will send output. 


Format: 
WRITE filename LRn] LBn] 


If the file specified is not already open, it is opened (see OPEN). Subsequent PRINT 
statements save data on the disk until a disk statement (ог a Ctrl-D character 
(ASCII code 4) alone) is printed. If the file is not on the disk, the message FILE NOT 
FOUND appears. 

The file will be written to as a sequential file if the R parameter is absent. In a 
sequential file, the B parameter specifies at which byte (character) the WRITE 
begins. If there is no B parameter, WRITE begins at the first byte in the file (byte 
0). 

If the R parameter is present, the file will be written to as a random-access file. 
The WRITE is to the record specified by the R parameter. 

In a random-access file, the B parameter specifies at which byte within the 
specified record the WRITE begins. If there is no B parameter, WRITE begins at 
the first byte in the record (byte O). 

The B parameter can be used to write starting at a point beyond the last 
character already in the file (or record). This data can be READ, but any attempt to 
READ intervening unused bytes generates the OUT OF DATA message. 

The numbers following R and B must be integers in the range O through 
32767. If unspecified, O is assumed. 

While WRITE is in effect, every character that the Apple ll outputs that would 
normally be sent to the screen is sent to the disk. This includes the question mark 
generated by INPUT and any error messages. | 

This is a DOS command, requiring PRINT and CrRL-D in programmed mode. 

May not be used in immediate mode. 
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XDRAW 


This Applesoft statement draws a high-resolution graphics shape on the screen 
and, if used a second time with the same parameters, erases that shape. 


Format: 
XDRAW exprnm [AT colh, rowh] 


Shape number exprnm from the shape table is drawn, with each point in the color 
that is the complement of the color on the screen at that point. Colors O and 3 are 
a complementary pair, as are 1 and 2, 4 and 7, and 5 and 6 (see Table 8-3). The 
scale and rotation of the shape must be set by SCALE and ROT commands before 
the XDRAW command is executed. 

You use XDRAW instead of DRAW so that you can easily erase a shape you 
have drawn. Since XDRAW draws in the color complementary to the color pre- 
viously at that point, if you execute two (ог four, six, etc.) XDRAW statements 
with the same parameters, whatever is on the screen will be unchanged. 

If you do not specify a location in the XDRAW statement, the shape is drawn 
starting at the point plotted by the last executed DRAW, XDRAW, or HPLOT com- 
mand. If you do specify a location, the shape is drawn starting at that point (co/h, 
rowh). 

The shape number, exprnm, must have a value between O and the number of 
shapes in the shape table (which must not exceed 255), inclusive. 

Not available in Integer BASIC. 


FUNCTIONS 


Apple ІІ BASIC functions are described below in alphabetical order. Nomenclature 
and abbreviations are described at the beginning of this chapter. 

Many of the functions are available only in Applesoft. Such functions are 
appropriately identified. 


ABS 


Returns the absolute value of a number. This is the value of the number without 
regard to sign. 


Format: 


ABS exprnm 
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ASC 


Returns the ASCII code number for a specified character. 


Format: 
ASC (expr) 


If the string is longer than one character, ASC returns the ASCII code for the first 
character in the string. The code returned will not necessarily be the lowest ASCII 
code (in the range O-95) for that character. The characters generated by ASCII 
codes between 96 and 255 duplicate those in the lower range on the display 
screen. However, they are not evaluated as the same character by relational 
operators such as <, >, and z. They may be treated differently by printers and 
other output devices as well. If the first character of expr$ is Стп.-@ (ASCII code 
0), the message ?SYNTAX ERROR is generated. If expr$ is a null string the 
message 7ILLEGAL QUANTITY ERROR is produced. 
ASCII codes are listed in Appendix l. 


ATN 


Returns the arctangent of the argument. 


Format: 
АТМ (exprnm) 
Computes the arctangent, in radians, of exprnm. The angle returned is in the range 


-т/2 through 7/2. 
Not available in Integer BASIC. 


CHR$ 
Returns the string value of the specified ASCII code. 


Format: 
СНН% (exprnm) 


Returns the character represented by the integer value of exprnm, interpreted as 
an ASCII code. You will find a table of ASCII character codes in Appendix |. Use 
this function to generate characters you cannot produce at the keyboard for con- 
trolling peripheral devices, etc. The value of exprnm must be in the range O 
through 255 or the message ?ILLEGAL QUANTITY ERROR will appear. 

Not available in Integer BASIC. 
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cos 


Returns the cosine of an angle. 


Format: 
COS (exprnm) 
Computes the cosine of exprnm radians. 
Not available in Integer BASIC. 


EXP 


Returns e raised to a power. 


Format: 
EXP (exprnm) 
Computes e (the base of natural logarithms, 2.71828183) raised to the power 
exprnm. 
Not available in Integer BASIC. 


FN 


Invokes a previously executed user-defined function. 


Format: 
FN varnm (exprnm) 

varnm is the name of the function. The value of the exprnm is assigned every- 
where the dummy variable occurs in the function definition, and the resulting 
expression is evaluated. See DEF FN in the Statements section of this chapter. 

A function may not be recursive, i.e., exprnm may not refer to FN varnm nor to 
any other function which refers to FN varnm. 

If you attempt to use FN varnm before the DEF FN varnm statement has been 
executed you will receive the ?UNDEF'D FUNCTION ERROR message. 

Not available in Integer BASIC. 


FRE 


Returns the number of bytes of memory currently available to an Applesoft pro- 
gram. 


Format: FRE (exprnm) 
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The memory available to you is that below the string storage area and above the 
array storage. If there are more than 32767 bytes of memory available, FRE 
returns a negative number. Add 65536 to this number to discover the actual 
amount of memory available. 

FRE also clears disused strings from the string storage area. When a string 
changes value during a program the old value of the string is left in memory, and 
the new value is added to the string storage area. Eventually this might infringe on 
memory you are using for something else. To prevent this problem, have a state- 
ment such as A - FRE (0) executed periodically in programs that use strings 
extensively. 

The value of exprnm is not used by FRE, but it will cause an error if it is illegal. 

Not available in Integer BASIC. 


INT 


Returns the integer portion of a number. 


Format: 
INT (exprnm) 


Returns the largest integer less than or equal to the value of exprnm. 
Not available in Integer BASIC. 


LEFT$ 


Returns the leftmost characters of a string. 


Format: 
LEFT$ (expr$, exprnm) 


Returns the leftmost exprnm characters of expr$. exprnm must be in the range 1 
through 255, and expr$ may not have more than 255 characters. If exprnm is 
greater that the length of expr$, the entire string is returned. 

Not available in Integer BASIC. 


LEN 


Returns the length of a string. 


Format: LEN (expr$) 


Counts the number of characters in expr$, including all spaces and nonprinting 
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characters. If expr$ has more than 255 characters (possible only if expr$ is a 
string expression involving concatenation) the message ?STRING TOO LONG 
ERROR is generated. 


LOG 


Returns the natural logarithm of a number. 


Format: 
LOG (exprnm) 
Computes the natural logarithm of exprnm. Returns ?ILLEGAL QUANTITY ERROR 


if exprnm is zero or negative. 
Not available in Integer BASIC. 


MID$ 


Returns any specified portion of a string. 


шы MID$ (expr$, exprnm, Lexprnm,]) 

Returns exprnm, characters from expr$, starting with the character exprnm,. If 
exprnm, is absent, MID$ returns the portion of expr$ from the character 
exprnm, through the last character. If the length of expr$ is less than exprnm,, 
the null string is returned. If there are fewer than exprnm, characters in expr$ 
after exprnm:, the result is the same as if exprnm, were absent. expr$ must not 
exceed 255 characters, and exprnm, and exprnm, must each be in the range 1 
through 255. 

Not available in Integer BASIC. 


PDL 


Returns the current value of the game control (paddle) specified. 


Format: 
PDL (exprnm) 


The value returned is an integer between O and 255 based on the rotation of pad- 
dle number exprnm, or the resistance of a device connected to game control 
socket exprnm. The game controls are numbered O through 3. If the paddle num- 
ber is less than О or greater than 255 the message ?ILLEGAL QUANTITY ERROR 
is displayed. If the paddle number is between 4 and 255, PDL returns a somewhat 
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unpredictable number between O and 255, and may cause various side effects 
such as a click from the speaker or a sudden shift in graphics mode. 

If two PDL instructions are executed consecutively or nearly consecutively, the 
second value may be affected by the first. Make sure that several instructions are 
executed between PDL functions (an empty FOR-NEXT loop will do). 


PEEK 


Returns the contents of a memory location. 


format, PEEK (memadr) 


The value returned is the decimal equivalent of the eight bits at memory location 
memadr. Appendix E lists some useful memory locations. 


POS 


Returns the column position of the cursor. 


F t: 
ыны POS (ехртт) 


The expression is a dummy; it is not used and therefore сап have any legal value. 
POS will return a value between O and 39. Character positions begin at O for 
the leftmost character. 
Not available in Integer BASIC. 


RIGHTS 


Returns the rightmost characters of a string. 


Format: 
RIGHTS (expr, exprnm) 


Returns the rightmost exprnm characters of expr$. The value of exprnm must be 
in the range 1 through 255, and expr$ may not have more than 255 characters. If 
exprnm is greater than the length of expr$, the entire string is returned. 

Not available in Integer BASIC. 


RND 


Returns a random number. 
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Format: 
RND (exprnm) 


Returns a random number, the range of which depends on the value of exprnm 
and the version of BASIC. 

In Integer BASIC, RND returns a random integer between O and the value of 
exprnm , exclusive of exprnm but inclusive of О. Thus, RND (1) always returns О, 
and RND (—2) produces a fifty-fifty mix of O and —1. Attempting to use RND (0) 
causes the message *** * > 32767 ERR to be displayed. 

In Applesoft, RND always returns a real number greater than or equal to O and 
less than 1. The value returned can be one of three types, depending on the sign 
of exprnm. 

If exprnm is positive, RND returns a different value each time it is used, unless 
a repeatable sequence has been started. 

A repeatable sequence starts when RND is used with a negative exprnm. Any 
particular negative value always starts the same sequence; subsequent positive 
arguments will return a repeatable sequence of random numbers. A different 
repeatable sequence is started by each different negative value of exprnm. This 
feature is useful for testing and debugging programs that use RND. 

If exprnm is 0 in Applesoft, RND returns the random number most recently 
generated (this is not affected by CLEAR or NEW). 


SCRN 


Returns the color code of the low-resolution graphics point with the specified 
coordinates. 


Format: 
SCRN (col, row) 


If the screen is in text mode, or the text window is present and the point specified 
is within it, SCRN returns the color code of half of the character. The color code of 
the top half of the character is returned if row is even, that of the bottom half if 
rowis odd. The ASCII code of the character at character position (a,b) (with а in 
the range 0-39 and b in the range 0-23) is returned by the expression 
SCRN(a,2*5) + 16*SCRN(a,2* b +1). Thus the character itself is returned by 
CHR$ (n), where n is the value returned by the above expression. 

If col is in the range 0-39, SCRN returns the color code of the graphics point 
(col, row). \f colis іп the range 40-47 and rowis in the range O-31, SCRN returns 
the color number of the graphics point (co/ 40, row +16). If co/is in the range 
40-47 and rowis in the range 32-47, SCRN returns a number unrelated to any- 
thing on the screen. 

If SCRN is used while the screen is in high-resolution graphics mode, the num- 
ber returned is related to the low-resolution graphics area of memory rather than 
the high-resolution display. 
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SCRN is only recognized as a reserved word if the next nonspace character is a 
left parenthesis. 


SGN 


Determines whether a number is positive, negative, or zero. 


Format: 
SGN (exprnm) 


The SGN function returns +1 if exprnm is positive, —1 if it is negative, and O if it 
is zero. 


SIN 


Returns the sine of an angle. 


Format: 
SIN (exprnm) 


Computes the sine of exprnm radians. 
Not available in Integer BASIC. 


SPC 


Moves the cursor right a specified number of positions. 


Format: 
SPC (exprnm) 


The SPC function is used in PRINT statements to print exprnm blank spaces. 
Therefore any characters which the cursor passes over are erased. 

The SPC function moves the cursor rightward from whatever column position 
the cursor happens to be at when the SPC function is encountered. This is in con- 
trast to a TAB function, which moves the cursor to some fixed column measured 
from the leftmost column of the display. 

Not available in Integer BASIC. 


SQR 


Returns the square root of a positive number. 
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Format: SOR (exprnm) 


A negative value of exprnm causes the ?ILLEGAL QUANTITY ERROR message. 
SOR (exprnm) operates faster than (exprnm)^(.5). 
Not available in Integer BASIC. 


STR$ 


Converts a numeric value to a string. 


Fonna STR$ lexprnm) 


The value of exprnm is converted to a string. The string characters are the same 
as those that would be printed by a PRINT exprnm statement. Therefore, STR$ 
(2/3) = ".666666667" and STR$ (2468013579) = “2.46801358Е--09”. If 
exprnm exceeds the limits for real numbers, the message ?OVERFLOW ERROR is 
displayed. 

Not available in Integer BASIC. 


TAB 


TAB moves the cursor right to the specified column position. 


Format; TAB (exprnm) 


Use TAB with the PRINT statement to move the cursor to column exprnm, if 
exprnmis to the right of the cursor's current position. The cursor does not move if 
exprnm is not to the right of the current position. TAB prints blank spaces as it 
moves the cursor right, thereby erasing anything that was on the screen 
beforehand. 

For TAB, columns are numbered from 1 to 255. If exprnm is larger than the 
width of the output device (40 for the display screen), it moves the cursor down 
one line and resumes counting at the left margin. If the value of exprnmis O, TAB 
moves to column 256. A value of exprnm outside the range O to 255 causes the 
error message ?ILLEGAL QUANTITY ERROR. 

See also HTAB (Applesoft) and TAB (Integer BASIC) in the Statements section 
of this chapter. 

Not available in Integer BASIC. 


TAN 


Returns the tangent of an angle. 
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Format: 
TAN (exprnm) 
Computes the tangent of exprnm radians. 
Not available in Integer BASIC. 


USR 


Branches to a machine language subroutine, passing values in the Accumulator. 


Format: 
USR exprnm 

The subroutine starts at memory location 10 (OA hexadecimal). Locations 10 
through 12 (OA through OC hexadecimal) must contain an assembly language 
JMP instruction that branches to the starting location of your subroutine. Since 
USR is a function, it returns a numeric real value. Whatever is in the Accumulator 
when the assembly language subroutine executes an RTS instruction (returning to 
the Applesoft program) is the value returned. 

There аге many useful machine language subroutines present in the Apple 1! 
Monitor. They are listed in Appendix D. 

See also the CALL statement described in the Statements section of this 
chapter, which is available in Integer BASIC also. 

Not available in Integer BASIC. 


VAL 


VAL converts a string to a numeric value. 


Format: 
VAL (expr$) 


Returns the numeric value represented by expr$ . If the first character of expr$ is 
not a numeric character, zero is returned. Otherwise, expr$ is taken character by 
character until an unacceptable character is encountered. The acceptable charac- 
ters are: the digits O through 9, spaces, a decimal point, a leading plus or minus 
sign, and in the context of scientific notation, an additional plus or minus sign, an 
additional decimal point, and the letter E. | 

If expr$ is a string expression involving concatenation that contains more that 
255 characters, the message ?STRING TOO LONG ERROR occurs. If the numeric 
value of expr$ exceeds the limits of real numbers, the message ? OVERFLOW 
ERROR occurs. 

Not available in Integer BASIC. 


A 


Derived Numeric Functions 


While the following list of derived functions is by no means complete, it does pro- 
vide some of the most frequently needed formulas. Certain values of x will invali- 
date some functions (for example, if COS(x)20 then SEC(x) is nonreal), so your 
program should check for them. 

None of the derived functions will operate in Integer BASIC. 


ARCCOS(x) = -ATN(x/SOR(-x «x +1))+1.5707633 
Returns the inverse cosine of x (ABS(x) « 1). 


ARCCOT(x) = -ATN(x)4 1.5707633 

Returns the inverse cotangent of x. 
ARCCOSH(x) = LOG(x+SQR(x «x – 1)) 

Returns the inverse hyperbolic cosine of x (x > = 1). 
ARCCOTH(x) = LOG(G-- 1)/(x-1)/2 

Returns the inverse hyperbolic cotangent of x (ABS(x > 1). 
ARCCSC(x) = ATN(1/SQR(x «x —1))+(SGN(x)—1)#1.5707633 

Returns the inverse cosecant of x (ABS(x) > 1). 
ARCCSCH(x) = LOG((SGN(x) *SQR(x «x 1) 4- 1)/x) 

Returns the inverse hyperbolic cosecant of x (x > 0). 


ARCSEC(x) = АТМ(ЅОВ (х «x —1))+(SGN(x)—1)#1.5707633 
Returns the inverse secant of x (ABS(x) > = 1). 


ARCSECH(x) = LOG((SOR(- x #x+1)+1)/x) 
Returns the inverse hyperbolic secant of x (O < x <= 1). 
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ARCSIN(x) = ATN(x/SQR(- x #x+1)) 
Returns the inverse sine of x (ABS(x) « 1). 


ARCSINH(x) = LOG(x+SQR(x «x4 1)) 

Returns the inverse hyperbolic sine of x. 
ARCTANH(x) = LOG((1+x)/(1-—x))/2 

Returns the inverse hyperbolic tangent of x (ABS(x) < 1). 
COSH(x) = (EXP(x)--EXP(- x))/2 

Returns the hyperbolic cosine of x. 
COT(x) = 1/TAN(x) 

Returns the cotangent of x (x < > 0). 
COTH(x) = EXP(—x)/(EXP(x)-EXP(—x))#2+1 

Returns the hyperbolic contangent of х (х < > 0). 
CSC(x) = 1/SIN(x) 

Returns the cosecant of x (x« > 0). 
CSCH(x) = 2/(EXP(x)—-EXP(-x)) 

Returns the hyperbolic cosecant of x (x < > 0). 
LOG, (x) = LOG(x)/LOG(a) 

Returns the base a logarithm of x (a > 0, x >0). 
106,0 (x) = LOG(x)/2.30258509 

Returns the common (base ten) logarithm of x (x > 0). 
Мора (x) = INT((x/a—INT ((x/a))* a+.05)* SGN (x /a) 

Returns x modulo a: the remainder after division of x by ala« > 0). 
SEC(x) = 1/COS(x) 

Returns the secant of x(x« > 7/2). 
SECH(x) = 2/(EXP(x) -EXP(- x)) 

Returns the hyperbolic secant of x. 
SINH(x) -(ЕХР(х)-ЕХР(-х)/2 

Returns the hyperbolic sine of x. 
TANH(x) = -EXP(—-xY/ EXP (x) -EXP(-x)) *2-4- 1 

Returns the hyperbolic tangent of x. 


Editing Commands 


This appendix summarizes the functions of the Apple ll keystroke editing com- 
mands. 


= Moves the cursor forward along the display line. Each 
character passed over is copied into memory as if it had 
been typed on the keyboard. Does not alter the screen 
display. 

= Backspaces the cursor along the display line, erasing 
passed-over characters from memory but not from the 
display screen. 

Rept Causes a character printed by another key to be repeated as 
long as both keys are held down. The Верт key must be 
pressed after the other key. 

CrRL.-X The Apple Il disregards the current display line and moves the 
cursor to the left margin on the next line down. 
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sequence. 
Esc-A 


Esc-B 


Esc-C 


Esc-D 


Esc-E 


Esc-F 


Esc-@ 
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Esc Key Sequences 


The following seven editing commands are two-key sequences. In each in- 
stance, press the Esc key, release it, and then press the second key of the 


Moves the cursor one position to the right. Does not alter the 
screen display nor change memory. 

Moves the cursor one position to the left. Does not alter the 
screen display nor change memory. 

Moves the cursor down one line. Does not alter the screen 
display nor change memory. 

Moves the cursor up one line. Does not alter the screen display 
nor change memory. 

Deletes all characters from the cursor to the end of the display 
line. 

Deletes all characters from the cursor to the end of the display 
screen. 

Clears the screen and moves the cursor to the upper left 
corner. 


Edit Mode Commands 


The following four editing commands require the Autostart Monitor. They are 
effective only in edit mode. Enter edit mode by pressing the Esc key and leave edit 
mode by pressing any key other than the |, J, К, М, Верт, CTRL, or Ѕніғт keys. 


| 
Ј 


K 


Moves the cursor up one line without leaving edit mode. 


Moves the cursor one position to the left without leaving edit 
mode. 


Moves the cursor one position to the right without leaving edit 
mode. 


Moves the cursor down one line without leaving edit mode. 
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Error Messages 


Error messages are grouped into three categories: Integer BASIC, Applesoft, and 
DOS messages, and are listed alphabetically within each category. 

DOS error messages and most Applesoft error messages have associated error 
codes. After an error has caused an ONERR GOTO branch to occur, the code for 
that error can be found in memory location 222. Table C-1, located at the end of 
this appendix, lists error messages by their code numbers. 


INTEGER BASIC ERROR MESSAGES 


#*# 255 ERR 
A value which should be between O and 255 is outside that range. 


### > 32767 ERR 
A number greater than 32767 or less than —32767 has been entered or 
calculated. 


+++ 16 FORS ERR 
More than 16 FOR loops are active. 


+++ 16 GOSUBS ERR 
Seventeen more GOSUB statements than RETURN statements have been 
executed. 
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+++ BAD BRANCH ERR 

А branch to a nonexistent line number has been attempted. 
### BAD NEXT ERR 

A NEXT with no matching FOR has been executed. 
### BAD RETURN ERR 

More RETURN statements than GOSUB statements have been executed. 
+++ DIM ERR 

The same array has been dimensioned more than once. 
+++ MEM FULL ERR 

More memory is needed than is available. 
+++ NO END ERR 

The very last instruction executed in a program was not END. 
### RANGE ERR 


An array has been referenced with a subscript less than zero or greater 
than the array's size, or an argument in an HLIN, VLIN, PLOT, TAB, or VTAB 
instruction was outside the prescribed range. 

RETYPE LINE 
An error has been generated Бу an INPUT response. А diagnostic message 
is displayed first, and then this directive. 

+++ STRING ERR 
An illegal string operation has been executed. 


### STR OVFL ERR 
A string has been assigned more characters than it was dimensioned for. 


+++ SYNTAX ERR 
An error in spelling, punctuation, or sequence, or any error not covered by 
another error message has occurred. 

### TOO LONG ERR 
More than 12 parentheses have been nested or more than 128 characters 
have been entered in one line. 
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?BAD SUBSCRIPT ERROR 
An array has been referenced with the wrong number of subscripts or with 
one or more subscripts exceeding their dimensions. Error code 107. 


?CAN'T CONTINUE ERROR 
An attempt to continue (with the CONT command) was made when no 
program existed, a fatal error had occurred, or a change had been made to 
the program. 
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?DIVISION BY ZERO ERROR 
An attempt has been made to divide by an expression that evaluates to 
zero. Error code 133. 


?FORMULA TOO COMPLEX ERROR 
More than two statements of the form IF string THEN have been executed. 
Error code 191. 


?ILLEGAL DIRECT ERROR 
An INPUT, DEF FN, or a GET command was entered in direct mode. 


?ILLEGAL QUANTITY ERROR 
А numeric value is outside the acceptable range for a string function, 
numeric function, graphics statement, and so forth. Error code 53. 


?NEXT WITHOUT FOR ERROR 
A NEXT with no matching FOR has been executed. A NEXT with no varia- 
ble name generates this error only if there is no active FOR. Error code O. 


?OUT OF DATA ERROR 
More DATA elements have been read than are available. Error code 42. 


?ООТ OF MEMORY ERROR 
Can be caused by any of the following: program too large, too many varia- 
bles, more than 10 levels of FOR loop nesting, more than 24 levels of 
subroutine nesting, more than 36 levels of parentheses nesting, LOMEM: 
set too high, or HIMEM: set too low. Error code 77. 


?OVERFLOW ERROR 
Too large or too small a number has been entered or calculated. The 
allowable range is approximately —1.7E--38 to 1.7E+38. Error code 69. 


?REDIM'D ARRAY ERROR 
A DIM statement for a previously dimensioned array has been executed. 
Most commonly occurs when an array was dimensioned by default. Error 
code 120. 


?RETURN WITHOUT GOSUB ERROR 
More RETURN statements than GOSUB statements have been executed. 
Error code 22. 


?STRING TOO LONG ERROR 
An attempt was made to concatenate strings totaling more than 255 
characters. Error code 176. 


?SYNTAX ERROR 
An error in spelling, punctuation, or sequence, or any error not covered by 
another message has occurred. Error code 16. 


?TYPE MISMATCH ERROR 
A numeric expression or variable has been used where a string should be, 
or vice versa. Also occurs when the two sides of an assignment statement 
do not match in type. Error code 163. 
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?UNDEF'D FUNCTION ERROR 
A user-defined function that has never been defined has been referenced. 
Error code 224. 


?UNDEF'D STATEMENT ERROR 
A branch to a nonexistent line number has been attempted. Error code 90. 


DOS ERROR MESSAGES 


DISK FULL 
Ап attempt has been made to store more information on a disk than it can 
hold. On a full disk this message may occur in place of a more appropriate 
message (e.g., FILE NOT FOUND.) Error code 9. 


END OF DATA 
An attempt has been made to read from a portion of a text file that has 
never been written to. Error code 5. 


FILE LOCKED 
Ап attempt has been made to use SAVE, BSAVE, WRITE, DELETE, or 
RENAME on a locked file. Error code 10. 


FILE NOT FOUND 
А file has been referenced that does not exist on the disk. This error only 
occurs if the DOS command that referenced the file does not create the 
file when it is not found. Error code 6. 


FILE TYPE MISMATCH 
A DOS command has referenced a file that is not of the required type. The 
LOAD, RUN, and SAVE commands may only be used with program files. 
The CHAIN command may only be used with an Integer BASIC program 
file. The OPEN, READ, WRITE, APPEND, POSITION, and EXEC commands 
may only be used with text files. The BLOAD, BSAVE, and BRUN com- 
mands may only be used with binary files. Error code 13. 


УО ERROR 
An unsuccessful attempt to store to or retrieve from a disk has been made. 
Some common causes are: the disk drive door is open, the disk has not 
been initialized, no disk is in the drive, or the disk is defective. Error code 8. 


LANGUAGE NOT AVAILABLE 
An attempt to change languages with FP or INT has been made when the 
desired language was not in ROM or on the disk, or an attempt to load or 
RUN a program was made when the language of the program was similarly 
unavailable. Error code 1. 


NO BUFFERS AVAILABLE 
Another file buffer was required when all the available file buffers were 
already in use. Error code 12. 
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TABLE C-1. Error Codes 


©з 


oOmn aa Бо -0 


NEXT without FOR 
Language not available 
Range error 

Write protected 

End of data 

File not found 

Volume mismatch 

/О error 

Disk full 

File locked 

Syntax error 

No buffers available 
File type mismatch 
Program too large 

Not direct command 
Syntax error 

RETURN without GOSUB 
Out of DATA 

Illegal quantity 
Overflow 

Out of memory 
Undefined statement 
Bad subscript 
Redimensioned array 
Division by zero 

Type mismatch 

String too long 
Formula too complex 
Undefined function 
Bad response to an INPUT 
CrnL-C has been struck 


Applesoft 
DOS 
DOS 
DOS 
DOS 
DOS 
DOS 
DOS 
DOS 
DOS 
DOS 
DOS 
DOS 
DOS 
DOS 
Applesoft 
Applesoft 
Applesoft 
Applesoft 
Applesoft 
Applesoft 
Applesoft 
Applesoft 
Applesoft 
Applesoft 
Applesoft 
Applesoft 
Applesoft 
Applesoft 
Applesoft 
Applesoft 


NOT DIRECT COMMAND 
The following DOS commands may only be used from within PRINT state- 
ments in programmed mode: APPEND, OPEN, POSITION, READ, and 
WRITE. Error code 15. 


PROGRAM TOO LARGE 
А DOS command has attempted to put a file from the disk in the Apple ll 
memory, and found insufficient memory to hold the file. Error code 14. 


RANGE ERROR 
A parameter used with a DOS command is outside of the range specified 
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for that parameter; for example, the D (drive) parameter must be either 1 
or 2. Error code 2 or 3. 

SYNTAX ERROR 
A DOS command has an error in spelling, punctuation, or sequence. Error 
code 11. 

VOLUME MISMATCH 
The V (volume) parameter in a DOS command does not match the volume 
number of the disk accessed. Error code 7. 

WRITE PROTECTED 


An attempt has been made to use SAVE, BSAVE, or WRITE on a write-pro- 
tected disk. Error code 4. 


D 


Intrinsic Subroutines 


The following two tables list a number of useful machine language subroutines 
available on the Apple ll. Table D-1 lists them by general function; it does not pro- 
vide complete information about each subroutine. Find the entry point listed in 
Table D-1 in the first column of Table D-2 for details on registers affected, etc. 

Table D-2 lists the subroutines in order by entry point. The third column shows 
which registers, if any, must contain specific values before the subroutine is 
executed. The fourth column shows which registers are affected by the execution 
of the subroutine. 

Most of these subroutines have an equivalent in a BASIC command, or can be 
accessed from BASIC with a single CALL instruction. These equivalents appear in 
Table D-2. Some of the BASIC commands listed are only available in Applesoft; 
they are marked with an A. 

Some subroutines, however, have no equivalent in either version of BASIC, and 
cannot be executed by a single CALL because one or more registers must be 
loaded with specific values prior to execution. Different techniques are required to 
handle this problem in the different versions of BASIC. 

Integer BASIC provides a fairly simple solution. First execute a CALL —182 to 
place the current values of the registers in read/write memory. Then POKE the 
desired values in memory location 69 for the A register, 70 for the X register, and 
71 for the Y register. Execute a CALL —193 to restore these values in the 
registers, and CALL the location of the subroutine you wanted to execute in the 
first place. 
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This technique does not work in Applesoft. You must instead write and 
execute a machine language subroutine that loads the registers with the desired 
values and then executes an assembly language JSR instruction to the entry point 
of the desired intrinsic subroutine. 


TABLE D-1. Intrinsic Subroutines Cross-Referenced by Function 


Plot a low-resolution graphics point. 

Draw а low-resolution horizontal line. 

Draw a low-resolution vertical line. 

Clear all 48 low-resolution graphics rows to black 
(if in text mode, sets to inverse “2”. 

Clears the top 40 low-resolution rows 
to black (or inverse “2. 

Graphics | Increment the current low-resolution 

graphics color by three. 

Set low-resolution graphics color. 

Read the color of a low-resolution grahics point. 

Set low-resolution graphics mode, clear screen, 
and set four line text window. 


Wait for keystroke while flashing cursor, and seed 
random number generator at locations $4E and $4F. 


Same as above except that escape codes 
are also allowed. 
Send carriage return to display screen, then allow input 
of an entire line of up to 256 characters. 
Send three blanks out to the currently 
selected output device. 
Send from one to 256 blanks to the 
currently selected output device. 
Send а carriage return and line feed to the Apple Il screen. 
Output a character to the currently 
selected output device. 
Output a character to the text window. 
Send BELL character (ASCII code 7) to the 
currently selected output device. 
Bell | Beep the onboard speaker for 1/10 second. 
Output Print the message ERR and beep the onboard speaker. 
Beep the onboard speaker. 
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TABLE D-1. Intrinsic Subroutines Cross-Referenced by Function (Continued) 


ж 
Text | Set the Apple ll screen їо 24 rows by 40 columns. $FB2F 

Window| Scroll the text window up one line. $FC70 

Send a backspace character to the screen, 
updating the cursor position. 

Move the cursor up one line. If the cursor is already at 

Cursor the top of the screen, it does not move. 

Control | Move the cursor down one line without 

changing its horizontal position. 


Scrolls the text window if the cursor 
is at the bottom of the screen. 


Clear the text window from the current cursor position 
to the lower righthand corner of the screen. 


Clear the text window from coordinates passed in 
Screen registers to the lower righthand corner of the screen. 


Clearing | Clear the entire text screen and move the cursor 


to the upper lefthand corner. 
Video 
Mode 


Clear the text from the current cursor position 
to the end of the line. 


Set inverse video.mode (black on white). $FE80 
Set normal video mode (white on black). $FE84 
Print Y and X register contents (in the format YYXX) 
on the currently selected output device. 
Print A and X register contents (in the format AAXX) 
on the currently selected output device. 
Print X register contents on the 
currently selected output device. 


Print A register contents on the 
currently selected output device. 


Restore register contents (valid only if intrinsic routine 
at $FF4A executed previously). 
Contents| Save register contents in reserved Page Zero locations. 


Read status of one paddle. 

Execute a delay loop. 

Return to BASIC, eliminating the program 
and variables in memory. 


Entry point for the monitor. 
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TABLE D-2. Intrinsic Subroutines by Entry Point 


Plot a graphics point on low- 
resolution page 1. 

Draw a low-resotution 
horizontal line. 


Draw a low-resolution 
vertical line. 


Clear all 48 low-resolution 
graphics rows to black (if in 
text mode, sets to all 87. 


Clear the low-resofution 
graphics rows, leaving the 
text window intact. 

Increment the current 
low-resolution graphics color 
by three. 


Set low-resolution graphics 
Color. 


Read the color of a 
low-resolution graphics point. 
Print Y and X register 
contents (in the format YYXX) 
on the screen or other output 
device selected. 


Print A and X registers (AAXX) 
as above. 


Print X register contents. 


Send three blanks out to the 
currently selected output 
device (determined by CSW 
contents). 


Send 1 to 256 blanks to the 
currently selected output 
device. 


Read status of paddle O, 1, 
2, or 3. 


Set the Apple ll text screen 
to 40 rows by 24 columns. 


Set low-resolution graphics 
mode, clear screen and set 
4-line text window. 


Send BELL character (ASCII code 7) 
to the current output device. 
Beep Apple Il speaker for 
1/10 second. 
Send a backspace character 
to the screen, updating 
cursor position. 
Move the cursor up one line. 
If already at the top of the 
screen, cursor does not move. 
Clear the text window from the 


present cursor position to the 
lower righthand comer of the 
screen. 


Clear the text window from 
coordinates passed in registers 
to the lower righthand corner 
of the screen. 

Clear the entire text screen 


and move the cursor to the 
upper lefthand comer. 


Registers to Load Before Calling 


Place row in A, column in Y. 


Row in A, left column in Y, 
right column at memory 
location 44. 


Column in Y, high row in A, 


low row at memory location 


45. 
None 


None 


Color number in А. 


Row іп А, column in Y. 


None 


Number of blank spaces in A; 
{toading О prints 256 blanks). 


Paddle number in X. 


None 


None 


None 


None 


None 


None 


Column in Y, row in A. 


^ Denotes BASIC commands available in Applesoft only. 


Registers Affected 


A 


А (contains color 
number) 


None 


O-FF in Y register. 
A contents destroyed. 


A 


AY 


BASIC 
Equivalent 


PLOT 


HLIN 


VLIN 


CALL - 1998 


GR 
(see $FB40) 


CALL -1985 


COLOR 
SCRN 


CALL -1728 


CALL -1727 


CALL - 1724 
CALL -1720 


SPC(14 
CALL -1718 


РОЦ? 
ТЕХТ 


GR 


CALL -1063 
CALL -1052 


CALL -1008 


CALL -998 


CALL -958 


CALL -954 


HOME4 
CALL -936 
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TABLE D-2. Intrinsic Subroutines by Entry Point (Continued) 


BASIC 
Equivatent 


Registers to Load Before Calling Registers Affected 


Send a carriage return and CALL -926 
line feed to the Apple 1 
screen. 


Move the cursor down one line : CALL -922 
without changing its horizontal 
position. Scrolls text up one 
line if cursor is at the bottom 
of the screen 


Scroll the text window up one 3 CALL -912 
tine. 


Clear text from the current А CALL -868 
Cursor position to the end of 
the line. Cursor position 
remains unchanged. 


Execute a delay loop which is Delay value (x ) in А CALL -856 
0.5(5х2 + 27x + 26) 
microseconds long. 


Watt for keystroke, flash Character returned CALL -756 
cursor while waiting. Seed ind. 
random number generator at X.Y 
memory locations 78 and 79. 


Same as $Е0 18. except that Character returned CALL -715 
escape codes are also мА. 
allowed. x, Y 


Send carriage return to Prompt character at memory Ү.А. INPUT 
screen; allow input of an location 51. X contains length 
entire line of data, up to of entry. Data 
256 characters. entered starts at 
memory location$200 
Print the value in the Data in А CALL -550 
accumulator as two 
hexadecimal digits. 
Output a character to the Character in А. 
currently selected output 
device. 


Output a character to the Character in A PRINT 
Apple text window 


Set inverse video (black-on- None INVERSE^ 
white text). CALL -384 


Set normal video mode (white- None NORMAL4 
on-black text). CALL -380 
Return to BASIC. eliminating None X, CALL -336 
the program and variables in 
memory. 


Print the message ERR and CALL -211 
beep onboard speaker 


Beep the onboard speaker A CALL -198 


Restore register contents Register contents CALL -193 
(valid only if intrinsic restored from these 
routine at SFF4A executed locations: 
previously). A register: 69 ($45) 
S register: 72 ($48) 
X register: 70 ($46) 
Stack Pointer: 73($49) 
Y register: 71 ($47) 
Save register contents None CALL -182 
in reserved Page O locations 
A register: 69 ($45) 
S register: 72 ($48) 
X register: 70 ($46) 
Stack Pointer: 73 ($491 
Y register: 71 ($47) 


Entry point for the monitor CALL -151 


^ Denotes BASIC commands available in Applesoft only. 


Useful PEEK and POKE Locations 


Each of the memory locations listed below is expressed in terms of a decimal 
number less than 32767 in magnitude. Memory locations above 32767 are 
expressed in terms of a negative number. There is a positive number which refers 
to the same location. Add 65536 to the listed negative location to get the positive 
equivalent (e.g., 65536 - 16384 = 49152). 

Some of the functions described below are actuated by just accessing them. 
This means that any time a PEEK statement accesses the specified memory loca- 
tion, the indicated action takes place. A POKE statement to the specified memory 
location also triggers the action, but because of the operating characteristics of 
the microprocessor in the Apple il, a POKE statement actually triggers the action 
twice. In this case, POKE is the same as two PEEK statements. Usually this makes 
no difference, but in cases like —16336 (Speaker Click) it does. The value placed 
in memory by the POKE statement is irrelevant in such address-actuated actions. 


TEXT WINDOW AND CURSOR CONTROL LOCATIONS 


32 Left Margin of the Text Window 
Specifies the column of the left text window margin. PEEK returns a value in 
the range O through 39, O being the left edge of the screen. Changing this 
location does not affect the width of the text window; the left and right 
margins both move. 
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If you POKE a value greater than 39 in this location, or if the value of this 
location plus the width of the text window exceeds 40, some or all of the 
output meant for the screen will be put in memory outside the screen area. 
This could destroy part of your program or other essential data. 


33 Text Window Width 
Specifies the width of the text window. The value in this location must be in 
the range 1 through 40. Changing this location sets the right margin at the 
column that is the specified number of characters away from the left margin 
(memory location 32). 

A value of zero in this location (i.e., a width of zero) can destroy the 
BASIC interpreter. If you POKE a value greater than 40 into this location, or if 
the value in this location plus the value in location 32 (left margin) exceeds 
40, some or all of the output meant for the screen will be put in memory 
outside the screen area. This could destroy part of your program or other 
essential data. 


34. Top Margin of the Text Window 
Specifies the top margin of the text window. The value in this location must 
be in the range О through 23; О specifies the top row on the screen, 23 the 
bottom. If you POKE a value greater than 23 into this location, some or all of 
the output meant for the screen will go into memory outside the screen area, 
wiping out data that could be important. Do not set the top margin of the 
text window below the bottom margin. 


35 Bottom Margin of the Text Window 
Specifies the bottom margin of the text window. The value in this location 
must be in the range O through 23; O specifies the top row on the screen, 
23 the bottom. If you POKE a value greater than 23 into this location, some 
or all of the output meant for the screen will go into memory outside the 
screen area, wiping out data that could be important. Do not set the bottom 
margin of the text window above the top margin. 


36 Horizontal Position of the Cursor 
Specifies the current horizontal position of the cursor. PEEK returns a value 
in the range O through 39; it specifies the cursor's position relative to the 
left margin of the text window (not necessarily the left edge of the screen). 
This location can be used to position beyond the right edge of the text win- 
dow (and subsequently print there with PRINT), but the cursor only stays 
there long enough to print one character. Do not put a value in this location 
that, when added to the left screen margin (location 32), exceeds 39. 
This PEEK is equivalent to the Applesoft function POS. 


37 Vertical Position of the Cursor 
Specifies the current vertical position of the cursor. PEEK returns a value in 
the range O through 23, relative to the top of the screen (not the top of the 
text window). Do not put a value over 23 in this location. 
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ERROR HANDLING LOCATIONS 


216 Error Flag 
Indicates whether an ONERR GOTO is in effect. If bit 7 of this memory loca- 
tion is 1 (i.e., if this location has a value of 128 or more), an ONERR GOTO 
statement has been encountered, and control will branch to the line number 
specified when an error occurs. POKE a value less than 128 to disable a pre- 
viously executed ONERR GOTO statement. 


218 and 219 Error-Causing Line Number 
When an error triggers a branch according to an ONERR GOTO statement, 
these locations specify the line number in which the error occurred. This line 
number is PEEK(219)4256-- PEEK (218). 


222 Error Type Code 


Specifies which type of error has occurred. The error codes and their 
descriptions are given in Appendix C. 


KEYBOARD LOCATIONS 


—16384 Character from Keyboard 
Reads the keyboard. If the value in this location is greater than 127 (е, if bit 
7 is 1), a key has been pressed. Determine the ASCII code of the key last 
pressed by subtracting 128 from this value. 


—16368 Keyboard Flag 
Resets keyboard strobe (bit 7 of location — 16384) to zero so that the next 
character may be read in. 


"CLICK" OUTPUT LOCATIONS 


—16352 Cassette Click 
Generates an audible click on the cassette output jack. 


—16336 Speaker Click 
Generates a click on the internal speaker. 


DISPLAY SWITCHES 


The memory locations listed in this section set certain switches which determine 
display characteristics. There are no real physical switches; only PEEK and POKE 
commands affect the settings. There are four switches which can each be set in 
two different positions, as shown in Figure E-1. With text mode selected, the only 
other switch that has any effect is the Page 1/Page 2 switch. 
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Graphics Full Screen Page 1 Low-Resolution 
-16304 -16302 -16300 -16298 


Graphics High-Resolution 
Plus Text —16297 
-16301 


FIGURE Е-1. PEEK/POKE Graphics and Text Locations 


—16304 Select Graphics Mode 
Selects graphics mode. The graphics screen is not cleared to black. The 
graphics mode may be low or high resolution, page 1 or page 2, full-screen 
graphics or mixed graphics and text. These characteristics are determined 
by other memory locations. 

—16303 Select Text Mode 
Selects text mode. The text may be from either page 1 or page 2; this is 
determined by other memory locations. 


—16302 Select Full-Screen Graphics 
Selects full-screen graphics. If the screen is in text mode, this will not be 
visible until location — 16304 is accessed. 
—16301 Select Graphics Plus Text 
Establishes a four-line text window at the bottom of the screen. If the screen 
is in text mode, this will not be visible until location —16304 is accessed. 
—16300 Select Screen Page 1 
Selects graphics or text page 1. 
—16299 Select Screen Page 2 
Selects graphics or text page 2. 
—16298 Select Low-Resolution Graphics 
Selects low-resolution graphics. If the screen is in text mode, this will not be 
visible until location —16304 is accessed. 
—16297 Select High-Resolution Graphics 


Selects high-resolution graphics. If the screen is in text mode, this will not be 
visible until location —16304 is accessed. 
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On On On On 
-16295 -16293 -16291 -16289 


FEO 


Off Off Off Off 
-16296 —16294 —16292 -16290 
Annunicator O Annunicator 1 Annunicator 2  Annunicator 3 


FIGURE E-2. Game Control Outputs (Annunicators) Manipulation 


GAME CONTROL LOCATIONS 


The memory locations in this section turn game control outputs on or off, sense 
whether pushbuttons are being pressed or not, and actuate a strobe output. 
Figure E-2 shows how the game control outputs are manipulated. 
All inputs and outputs for these PEEK and POKE statements connect to the 
game control connector, pictured in Figure E-3. 
—16296 Annunciator O Off 
Turns off game control output (annunciator) number 0. The voltage on pin 
15 of the game control connector is set to approximately O volts (TTL high). 
—16295 Annunciator O On 
Turns on game control output (annunciator) number 0. The voltage on pin 
15 of the game control connector is set to approximately +5 volts (TTL 
low). 
—16294 Annunciator 1 Off 
Turns off game control output (annunciator) number 1. The voltage on pin 
14 of the game control connector is set to approximately O volts (TTL high). 
—16293 Annunciator 1 On 
Turns on game control output (annunciator) number 1. The voltage on pin 
14 of the game control connector is set to approximately +5 volts (TTL 
low). 
—16292 Annunciator 2 Off 
Turns off game control output (annunciator) number 2. The voltage on pin 
13 of the game control connector is set to approximately O volts (TTL high). 
-16291 Annunciator 2 On 
Turns on game control output (annunciator) number 2. The voltage on pin 
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13 of the game control connector is set to approximately +5 volts (TTL 
low). 


—16290 Annunciator 3 Off 
Turns off game control output (annunciator) number 3. The voltage on pin 
12 of the game control connector is set to approximately O volts (TTL high). 


—16289 Annunciator 3 On 
Turns on game control output (annunciator) number 3. The voltage on pin 
12 of the game control connector is set to approximately +5 volts (TTL 
low). 


—16287 Read Pushbutton O 
When the pushbutton on game control number O is being pressed, the value 
in this location exceeds 127; when it is not being pressed, the value is 127 
or less. Pushbutton O connects to pin 2 of the game control connector. 


—16286 Read Pushbutton 1 
When the pushbutton on game control number 1 is being pressed, the value 
in this location exceeds 127; when it is not being pressed, the value is 127 
or less. Pushbutton 1 connects to pin 3 of the game control connector. 


—16285 Read Pushbutton 2 
When the pushbutton on game control number 2 is being pressed, the value 
in this location exceeds 127; when it is not being pressed, the value is 127 
or less. Pushbutton 2 connects to pin 4 of the game control connector. 
—16272 Strobe Output 
Normally pin 5 of the game control connector is +5 volts. If you PEEK 
memory location —16285, it drops to O volts for one-half microsecond. 
POKE will trigger the strobe twice. 


Game 1/0 


оооооооо 
оооооооо 


FIGURE E-3. Game Control Inputs and Outputs 


Е 


BASIC Reserved Words 


The Apple il interprets every occurrence of the following reserved words as а 
BASIC command, statement, or function. The only exception is when they are 
part of text strings enclosed in quotation marks. So keep reserved words out of 
your variable names. Watch especially for the short reserved words. 

You may enter reserved words with embedded blank spaces; the Apple Il will 
compress the blanks out. 


INTEGER BASIC 


ABS END LET PDL SAVE 
AND FOR LIST PEEK SCRN 
ASC GOSUB LOAD PLOT SGN 
AT GOTO LOMEM: POKE STEP 
AUTO GR MAN POP TAB 
CALL HIMEM MOD PRINT TEXT 
COLOR= HLIN NEW PR# THEN 
CON IF NEXT REM TO 
DEL IN3F NOT RETURN TRACE 
DIM INPUT NOTRACE RND VLIN 
DSP LEN OR RUN VTAB 
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APPLESOFT 


Reserved words in Applesoft are tokenized: each word takes up only one byte of 
program storage. The tokens are listed with each reserved word below. They are 
also listed in numerical order in Appendix l. 
Applesoft will not recognize the reserved word TO properly if: 
1. The first nonblank character before TO is the letter A, and 
2. One or more blanks separate the T and O. 


ABS (212) HTAB (150) REM (178) 
AND (205) IF (173) RESTORE (174) 
ASC (230) IN + (139) RESUME (166) 
AT (197) INPUT (132) RETURN (177) 
ATN (225) INT (211) RIGHT$ (233) 
CALL (140) INVERSE (158) RND (219) 
CHR$ (231) LEFT$ (232) ROT= (152) 
CLEAR (189) LEN (227) RUN (172) 
COLOR= (160) LET (170) SAVE (183) 
CONT (187) LIST (188) SCALE= (153) 
COS (222) LOAD (182) SCRN( (215) 
DATA (131) LOG (220) SGN (210) 
DEF (184) LOMEM: (164) SHLOAD (154) 
DEL (133) MID$ (234) SIN (223) 
DIM (134) NEW (191) SPC( (195) 
END (128) NEXT (130) SPEED- (169) 
EXP (221) NORMAL (157) SQR (218) 
FLASH (159) NOT (198) STEP (199) 
FN (194) NOTRACE (156) STOP (179) 
FOR (129) ON (180) STORE (168) 
FRE (214) ONERR (165) STR$ (228) 
GET (190) OR (206) TAB( (192) 
GOSUB (176) PDL (216) TAN (224) 
GOTO (171) PEEK (226) TEXT (137) 
GR (136) PLOT (141) THEN (196) 
HCOLOR= (146) POKE (185) TO (193) 
HGR (145) POP (161) TRACE (155) 
HGR2 (144) POS (217) USR (213) 
HIMEM: (163) PRINT (186) VAL (229) 
HLIN (142) PR 4# (138) VLIN (143) 
HOME (151) READ (135) VTAB (162) 
HPLOT (147) RECALL (167) WAIT (181) 


XDRAW (149) 
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DOS 


DOS commands are only considered reserved words if they are used in immediate 
mode or in a PRINT statement that begins with a Crn.-D character (ASCII code 4). 


APPEND CHAIN INIT POSITION SAVE 
BLOAD CLOSE LOAD READ UNLOCK 
BRUN DELETE LOCK RENAME VERIFY 


BSAVE EXEC OPEN RUN WRITE 


G 


Memory Usage 


GENERAL MEMORY ORGANIZATION 


The Apple ІІ memory is divided into three general categories: read/write memory 
(also called random access memory or RAM), read-only memory (НОМ), and 
input/output locations (1/0). Memory locations О through 49151 (ФВЕЕЕ hex- 
adecimal) are in RAM, locations 49152 (%С000) through 53247 ($CFFF) are іп 
ROM. Your system does not necessarily have actual memory for all of these loca- 
tions. For instance, if you have only 16K of RAM, memory locations 16384 
($4000) through 49151 ($BFFF) are not usable. 

Table G-1 shows how memory is allocated оп an Apple Il system. Notice there 
are two blocks of free memory locations, surrounding the two high-resolution 
graphics pages. The system pointer LOMEM: keeps track of the lower bound on 
this free area, and the system pointer HIMEM: marks the upper end. This read/ 
write memory can be used for a number of things. Among them are the nonfirm- 
ware Applesoft interpreter (from cassette or disk), the Disk Operating System 
(DOS), high-resolution graphics, and your BASIC program and its variables. 
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TABLE G-1. BASIC Memory Organization 


Location 


0-255 $0-SOFF System programs 

256-511 $100-$1FF System stack 

512-767 $200-$2FF Keyboard input buffer 

768-1023 $300-$3FF Monitor vector locations 
1024-2047 $400-$7FF Text and low-resolution graphics page 1 
2048-3071 $800-$BFF Text and low-resolution graphics page 2 
3072-8191 $COO-$1FFF Free 
8192-16383 | $2000-$3FFF High-resolution graphics page 1 


16384-24575 
24576-49151 
49152-49279 
49280-49407 
49408-51199 
51200-53247 
53248-65535 


$4000-$5FFF 
$6000-$BFFF 
$CO00-$CO7F 
$CO80-$COFF 
$C100-$C7FF 
$C800-$CFFF 
$D000-$FFFF 


High-resolution graphics page 2 

Free 

Special built-in locations 

Peripheral card І/О space 

Peripheral card memory 

Peripheral card expansion memory 
Integer BASIC, Applesoft, the Monitor 
or the Autostart Monitor, etc. 


THE BASIC LANGUAGE INTEPRETERS 


As you can see in Table G-1, the Integer BASIC interpreter always resides in ROM. 
The Applesoft interpreter also resides in ROM if your system has the Applesoft 
Firmware card or the Language System installed. Otherwise, the Applesoft 
interpreter occupies approximately 10K bytes of memory starting at 2048 
($800). 


DOS MEMORY REQUIREMENTS 


You need at least 16K of memory to use DOS. When booted, DOS takes up 
approximately 10K at the top of memory. НІМЕМ: is set just below the memory 
used by DOS. Figure G-1 shows which sections of memory are used by DOS on 
various sizes of systems. Note that you must have at least 24K of RAM to support 
both DOS and disk (or cassette) Applesoft, and at least 32K to use page 1 of 
high-resolution graphics with DOS. Figure G-1 also clearly shows the conflict be- 
tween disk (or cassette) Applesoft and high-resolution graphics page 1. 

DOS uses several additional sections of memory while it is booting (see Figure 
G-2). Anything in those areas before booting will be gone after booting. 


INTEGER BASIC MEMORY USAGE 


Integer BASIC program lines reside in the high end of free read/write memory, 
starting at HIMEM:. As shown in Figure G-3, HIMEM: is automatically adjusted as 
you add, delete, and change program lines. 
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Legend 
С) Non-firmware 
Applesoft Interpreter 
ГГ High Resolution Graphics 
Page 1 
С High Resolution Graphics 
Page 2 
С] System 
C] DOS (uses 10,752 bytes) 
0 С] Free space 


16K 20K 24K 32K 36K 48K 
Size of System 


e 
o 
E 
Ф 
> 
5 
m 
Ф 
ES 
a 


FIGURE G-1. Read/Write Memory (RAM) Usage 


Highest RAM address (HIMEM:) 


DOS is relocated. 1—1 0,752 ($2A00) bytes 


.. here at end of boot — 


Ж -DOS is first put here | 


2559 ($9FF) 
uffers used during boot 2048 ($800) 

к о a и 1023 ($3FF) 
. r 

|. | Bootstartshere — | i 768 ($300) 


FIGURE G-2. Memory Used During DOS Boot 


Variables are stored starting at LOMEM: and working up. As variable storage 
requirements change, LOMEM: adjusts automatically. Each numeric variable is 
mapped into memory with four attributes: the variable name, the DSP on/off byte, 
the memory location of the next variable, and the actual value or values of the 
variable. 

The variable name may be up to 100 characters long. Each character is repre- 
sented in memory by its ASCII code, with the high-order bit set to 1. 
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This address can be found 
Program lines in locations 202 and 203 (HIMEM:) 
build down 


This address can be found 
Variable storage in locations 204 and 205 (LOMEM:) 


builds up 


FIGURE G-3. Integer BASIC Program Memory Map 


The DSP byte indicates whether the BASIC command DSP is in force for this 
variable. This byte, normally O, is set to 1 when DSP is executed for this variable, 
and reset to O when NO DSP is executed. 

The address of the next variable is stored in two bytes, low-order first. 

The data is stored in pairs of bytes, low-order byte first. If the variable is not an 
array, there is only one such pair. If the variable is an array, there is one pair per 
element, listed in order starting with element zero. There is no distinction between 
a simple variable and an array with the same name; the simple variable is the zero 
element of the array. 

String variables are stored similarly. The variable name, DSP byte, and next 
variable address are stored in the same fashion as numeric variables. The ASCII 
code for each character of the string takes one byte, with the high-order bit set to 
1. The last character of the string is followed by a string terminator byte, in which 
the high-order bit is O. 


APPLESOFT MEMORY USAGE 


Applesoft program lines occupy the low end of free read/write memory starting at 
(ОМЕМ:, as shown in Figure G-4. As you add, delete, and change program lines, 
LOMEM: adjusts automatically. Simple numeric variables and string pointers are 
stored directly above the program lines. Arrays and string array pointers are 
stored above the simple variables. String va/ues are stored at the top of memory, 
starting at HIMEM:. As you use more string values, HIMEM: automatically adjusts 
downward. 

Each numeric variable and string pointer uses seven bytes of memory. Each 
real variable uses two ASCII codes (two bytes) for the variable name (both with 
the high-order bit set to O). The value is stored in scientific notation with one byte 
for the exponent and four bytes for the mantissa. The bytes of the mantissa are in 
order from the most significant byte to the least significant byte. 
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String storage 
builds down 


Array variables and 
string pointers 


Simple variables and 
string pointers 


Program lines 
push LOMEM: up 


FIGURE G-4. Applesoft Program Memory Map 


Each integer variable also uses two ASCII codes (two bytes) for the variable 
name (both with the high-order bit set to 1) and two bytes for the value of the 
variable, high-order byte first. 

Each string pointer uses two ASCII characters (two bytes) for the variable 
name (the high-order bit of the first is 1, that of the second is O), one byte for the 
length of the string, and two bytes for the address of the string value, low-order 
byte first. The last three bytes of an integer variable and the last two of a string 
pointer are unused. 

Numeric arrays and string pointer arrays are stored immediately above the 
variables. The name of the variable is stored as an ASCII code in the first two 
bytes; both high-order bits are O for real variables, both are 1 for integer variables, 
and the first is 1 and the second O for string pointers. 

The variable name is followed by two bytes indicating the location of the next 
variable. This is given relative to the first byte of this variable name, low-order 
byte first. Next is one byte for the number of dimensions, then two bytes per 
dimension (high-order first) indicating the size of each dimension. The sizes are 
listed in reverse order, i.e., the size of the first dimension is shown last. 

Each element of the array is then listed, from element (0,0,. . .,0) to element 
(N,N,. . .N). The elements are stored in order, with the leftmost index incremented 
first. Each real array element uses five bytes, one for the exponent, and four (most 
significant first) for the mantissa. Each integer element uses two bytes, high-order 
first. Each string pointer element uses three bytes, one for the length of the string 
and two (low-order first) for the address of the string. 
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String values are stored at the high end of free read/write memory. They 
require one byte of memory per character. Duplicate strings are only stored once; 
two or more string pointers can point to one location. As new string values are 
created, they are placed in the next available free space (HIMEM: adjusts down- 
ward). Strings that are no longer being used stay in memory. The FRE function 
forces a garbage collection, eliminating all abandoned strings and resetting 
НІМЕМ:. 


H 


Disk Il Format 


Information is stored on the diskette in 35 concentric bands, called tracks. These 
tracks are numbered O through 34 ($0 through $22). Each track is divided into 16 
segments, called sectors, numbered O through 15 ($0 through $F). Each sector 
can hold up to 256 bytes of data. There are a total of 455 sectors on the disk, 
holding up to 116,480 bytes of data. 

DOS transfers data to and from the disk one sector at a time. It uses two 256- 
byte file buffers in memory, one for reading and one for writing, for each active 
file. 

Each type of file (text, program, and binary) has its own format on the disk. 
Text files are stored in ASCII code, one byte per character. A zero byte marks the 
end of the file. All bytes of a text file are interpreted as text. 

The first two bytes of the first sector of a BASIC program file indicate program 
length, low-order byte first. The remainder of the file contains the program, in 
ASCII code. In an Applesoft file, reserved words are tokenized rather than spelled 
out (a token is a single ASCII code byte). See Appendix F for a list of tokens in 
alphabetical! order and Appendix І for a list in numerical order. 

The first two bytes of the first sector of a binary file show the starting address 
for the binary data in read/write memory, low-order byte first. The next two bytes 
show the length of the file, low-order byte first. The remainder of the file contains 
binary data. 
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THE TRACK/SECTOR LIST 


DOS normally writes to the disk wherever it can find a free sector. This means 
that one multisector file may be scattered over several tracks. DOS makes a list of 
the track and sector numbers used by each file and stores it in one or more addi- 
tional sectors on the diskette. This is called the track/sector list. 

Each sector of the track/sector list contains a pointer to the next sector of the 
track/sector list (if any) and points to as many as 122 file-contents sectors. 

If a sector of a file is unused, the pointer to it in the track/sector list is O. If an 
entire sector at the beginning of the track/sector list has zero pointers, that sector 
is not stored on the disk. Thus, if record number 5000 is the first and only record 
in a random-access file that has an L parameter of 256 (one record per sector), 
only two diskette sectors will be used: one for the data in record number 5000, 
and one for the 41st sector of the track/sector list. 

Byte O and bytes 3 through 12 of the track/sector list sector are not used. 
Bytes 1 and 2 contain the track and sector numbers, respectively, of the next sec- 
tor of the list. If these bytes are both O, this is the last sector of the list. 


THE DIRECTORY 


DOS uses track 17 ($11) for the diskette directory. For each file, the directory 
contains the name of the file, the file type, the number of sectors occupied by the 
file (modulo 256), and the location of the file's track/sector list. Most of this infor- 
mation is displayed on the screen by the CATALOG command. 

Each sector of the directory contains information for up to seven files. The 
directory begins in track 17, sector 15. When this sector is filled up, the directory 
continues in sector 14, and so on, through sector 1. The directory can contain 
entries for up to 84 files. 

Byte O and bytes 3 through 10 of each directory sector are not used. Bytes 1 
and 2 contain, respectively, the track and sector numbers of the next sector of the 
directory. If both are O, this sector is the last in the directory. Bytes 11 through 
255 contain the directory entries. Each entry takes 35 bytes; the first entry is in 
bytes 11 through 45, the second is in bytes 46 through 80, etc. 

Directory entries are all written in the same format. Table H-1 itemizes the con- 
tents of each entry. Table H-2 explains how the file type is encoded in each direc- 
tory entry. 

Sector O of track 17 does not have directory entries. Instead, it holds identifica- 
tion status, physical description, and space availability information for the disk. 
Table H-3 outlines the contents of this important sector, called the Volume Table 
of Contents. 

Each four-byte group from byte 56 through 195 of the Volume Table of Con- 
tents contains an availability map for one of the disk's tracks. Each map identifies 
which sectors of the associated track are in use and which are available. A bit has 
a value of O when the corresponding sector is in use. It has a value of 1 when the 
corresponding sector is free. Table H-4 shows which bytes identify which sectors. 
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Relative 
Byte Number 


TABLE Н-1. Directory Entry Format 


Contents of Byte 


Track number of the file's track/sector list. Changed to 255 
when the file is deleted (former contents retained in relative 
byte 34). 

Sector number of the file's track/sector list. 

File type. See Table H-2. 

File name, іп ASCII. 

Number of sectors used by the file, modulo 256. 

End mark. Normally O, but changed to the former contents 

of relative byte O when the file is deleted. 


TABLE H-2. Disk Directory File Type Encoding 


в [тш — 


File is an Integer BASIC program file if this bit is 1. 
File is an Applesoft program file if this bit is 1. 

File is a binary file if this bit is 1. 

Reserved for future expansion. 

File is locked if this bit is 1. 


If bits O through 6 are all O, file is a text file. 


TABLE H-3. Volume Table of Contents (Sector O, Track 17) 


Not used 
Track number of first directory sector 
Sector number of first directory sector 
DOS release number 
4-5 Not used 
6 Diskette volume number 
7-38 Not used 
39 Maximum number of track/sector pairs possible in each 
sector of a track/sector list 
40-47 Not used 
48-51 Mask for the sector availability maps 
52 Number of tracks per diskette 
53 Number of sectors per diskette 
54-55 Number of bytes per sector: low-order byte in 54, high-order 
. byte in 55 
56-59 Sector availability map, track O 
60-63 Sector availability map, track 1 
64-195 Sector availability maps, tracks 2 through 195 
196-255 Not used 
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TABLE H-4. Sector Availability Map 


Second 


7 
6 
5 
4 
3 
2 
1 
0 
7 
6 
5 
4 
3 


— = «ші 
оОоэмоһоао-аоос2о 


Unused 
Unused 
Unused 


ASCII Character Codes and 
Applesoft Reserved Word Tokens 


The first table in this appendix shows ASCII codes 1 through 96 and the charac- 
ters they represent. ASCII codes in the range 96 through 127 produce the same 
characters on the Apple Il display screen as codes 64 through 95, although on 
some other output devices codes 96 through 127 produce lower-case letters. No 
keystrokes generate codes 96 through 127. 

ASCII codes 128 through 255 repeat codes O through 127. No keystroke will 
generate them. 

The second table in this appendix lists the Applesoft reserved words. Each 
reserved word takes up only one byte in program memory. Each reserved word is 
represented by a code, called a token, in the range 128 through 255. The token 
replaces the spelled-out reserved word in the Apple ІІ memory and on the disk. 
The list is in numerical order by token. Appendix F contains a list of reserved 
words in alphabetical order. 
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ASCII | Display Screen 
Code Character 
0 


ASCII Character Codes 


ASCII | Display Screen 
@ 48 0 0 


CTRL- 
CrRL-À 
Ста.-В 
Стаһ-С 
CrRL.-D 
CrRL.-E 
Crri-F 
Crat-G 
CrRL-H or -— 
Ста:-! 

CrRL.-J 

Стні-К 

Crat-L 
Crri-M 
CrRL-N 
Crri-O 

Стп.-Р 
Cra.-Q 
CrRL.-R 

Crr-S 

Стяһ-Т 

CrRL-U ог — 
CTRL-V 
Ств-М/ 

Cri. -X 

CrRL-Y 

CTRL-Z 

Esc 
n.a. 
CrRL.-Suirr-M 
CTRL- ^ 
n.a. 
space bar 


(bell) 
(backspace) 


oOMAnNOA A PWH ~ 


" «04001 PWN — 
с DOAN A OAWNH — 


(linefeed) 


(carriage return) 


(forward space) 


(cancel line) 


oe 


PTT TNX XS SK CANDO VSOSSTO ACT TOA ™MmMIOWPSO~y lA” 
BaN<XS<CHHMBHPVOZEZHAC-TA™MMIOADSOArVIA- 


> 


2 
Ф 


n.a. = not available оп the Apple ll keyboard. 
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Applesoft Reserved Word Tokens 


Пезегмес пазе тоя Reserved 


END 
FOR 
NEXT 
DATA 
INPUT 
DEL 
DIM 
READ 
GR 
TEXT 
PRH 
ІМЕ 
CALL 
PLOT 
HLIN 
VLIN 
HGR2 
HGR 
HCOLOR= 
HPLOT 
DRAW 
XDRAW 
HTAB 
HOME 
ROT= 
SCALE= 
SHLOAD 
TRACE 
NOTRACE 
NORMAL 
INVERSE 
FLASH 
COLOR= 
POP 
VTAB 
HIMEM: 


vum 
ONERR 
RESUME 
RECALL 
STORE 
SPEED= 
LET 
GOTO 
RUN 

IF 
RESTORE 
& 
GOSUB 
RETURN 
REM 
STOP 
ON 
WAIT 
LOAD 
SAVE 
DEF 
POKE 
PRINT 
CONT 
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Conversion Tables 


This appendix contains the following conversion tables: 


* Hexadecimal-Binary Numbers 
e Hexadecimal-Decimal Integers 


Hexadecimal- Binary Conversion Table 


Use the table below to convert between hexadecimal numbers in the range O-OF 
and binary numbers in the range 0000-1111. 

Convert larger binary numbers to hexadecimal numbers by converting four bin- 
ary digits at a time, working from right to left. If there are fewer than four binary 
digits in the leftmost group, add leading zeros. Here is an example: 

100101, = 00100101, 
2 5 
ee 
25,6 
Convert hexadecimal numbers larger than OF to binary one digit at a time. Here is 
an example: 


жеге, жаза». 
0110 0111 
SN a 

01100111, 
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HEXADECIMAL-DECIMAL INTEGER CONVERSION TABLE 


The toble below provides for direct conversions between hexa- 
decimal integers in the range O-FFF ond decimol integers in 
the range 0-4095. For conversion of lorger integers, the 
toble values may be odded to the following figures: 


Hexadecimal Decimal Hexadecimal Decimal 
21 000 4 096 20 000 131 072 
02 000 8192 30 000 196 608 
03 000 12 288 40 000 262 144 
04 000 l6 384 50 000 327 680 
05 000 20 480 60 000 393 216 
06 000 24 576 70 000 458 752 
07 000 28 672 80 000 524 268 
08 000 32 768 90 000 589 824 
09 000 36 864 А0 000 655 360 
ОА 000 40 960 80 000 720 8% 
0B 000 45 056 Co 000 786 432 
oC 000 49 152 00 000 851 968 
0D 000 53 248 EO 000 917 504 
OE 000 57 344 FO 000 983 040 
OF 000 61 440 100 000 1 048 576 
10 000 65 536 200 000 2 097 152 
11 000 99 632 300 000 3 145 728 
12 000 73728 400 000 4 194 304 
13 000 77 824 500 000 5 242 880 
14 000 81 920 600 000 6 291 456 
15 000 86 016 700 000 7 340 032 
16 000 90 112 800 000 8 388 608 
17 000 94 208 900 000 9 437 184 
18 000 98 304 АСО 000 10 485 760 
19 000 102 400 800 000 11 534 3% 
1A 000 106 4% С00 000 12 582 912 
ІВ 000 110 592 DOO 000 13 631 488 
ІС 000 114 688 Е00 000 14 680 064 
10 000 118 784 F00 000 15 728 640 
ТЕ 000 122 880 1 000 000 16 777 216 
1Е 000 126 976 2 000 000 33 554 432 


Hexodecimol fractions may be converted to decimal fractions 
as follows: 


1. Express the hexadecimal fraction os an integer times 
167^, where n is the number of significant hexadecimal 
ploces to the right of the hexodecimol point. 


0. САФВЕЗ = САЎ ВЗ, х 1676 
2. Find the decimal equivalent of the hexadecimol integer 


CA9 83, = 13 278 19519 


3. Multiply the decimal equivalent by 1677 


13 278 195 
x 596 046 448 x 10719 
0.791 442096 g — 


Decimal fractions moy be converted to hexadecimal froctions 
by successively multiplying the decimal fraction by 16) 9. 
After each multiplication, the integer portion is removed to 
form a hexadecimal fraction by building to the right of the 
hexodecimol point. However, since decimal orithmetic is 
used in this conversion, the integer portion of each product 
must be converted to hexedecimol numbers. 


Example: Convert 0.895} to its hexadecimal equivalent 


03 
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HEXADECIMAL-DECIMAL INTEGER CONVERSION (Continued) 
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HEXADECIMAL-DECIMAL INTEGER CONVERSION (Continued) 
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HEXADECIMAL-DECIMAL INTEGER CONVERSION (Continued) 
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HEXADECIMAL-DECIMAL INTEGER CONVERSION (Continued) 
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HEXADECIMAL-DECIMAL INTEGER CONVERSION (Continued) 
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Screen Layout Forms 


Use the forms in this appendix to plan the appearance of the display screen. On 
the text screen form, row and column numbers start with 1, which is appropriate 
for text work. On the low-resolution graphics screen form, row and column num- 
bers in it start with O, as do low-resolution graphics commands. 


цәә126 іхә1 


Vertical Tab Position 
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ABS, 312 
Accumulator, 236, 238-39 
Addressing modes, assembly language, 251 
Annuciators, game controls, 343-44 
APPEND, 186, 283. See a/so OPEN 
machine langauge fix for, 264 
Apptesoft. See a/so Programs 
accessing from Monitor, 233 
commas in, 114—15 
line numbers, 57 
memory usage, 352—55 
numeric values, 40 
program tine length, 42 
program listing, 46 
reserved word tokens, 347, 361 
restarting, 33-35 
restarting via CTRL-Y, 249 
switching to Integer BASIC, 49-50, 192 
tab stops in, 114—15 
variable names, 64-65 
Applesoft Firmware card, 7 
Arithmetic expressions, 70 
Arrays 
dimensions, 67 
index, 66 
initialization, 146, 154 
names, 66 
redimensioning, 80 
storing on cassette, 151-52 
Arrow keys, 18-19, 32 
ASC, 313 | 
ASCII 
codes, 360 
programming characters in, 122-23 


Index 


Assembly language 
with BASIC, 106, 259-60 
built-in subroutines, 258—60 
debugging, 255-57 
listing programs, 254-55 
Mini-Assembler, 251-54 
programs on disk, 186-87 
relocating, 259-60 
Assembly Language Monitor. See Monitor 
Assignment statements, 76 
ATN, 313 
AUTO, 47, 156, 264 
Automatic line numbering, 47 
Autostart Monitor. See Monitor 


BASIC, 15. See also Applesoft; Integer 
BASIC 
accessing, 28 
with assembly language, 227-29 
prompt characters, 38 
restarting, 33-35 
starting up, 29, 37-38 
versions of, 28, 192 
Backspace. See Left-arrow key 
Binary arithmetic, 248-49 
Binary Image Files. See Files, 
machine language 
Blank spaces, 58 
BLOAD, 196, 221, 242-43, 265 
verifying, 247 
Boolean expressions, 73 
Booting DOS, 22-26, 49 
Applesoft, 167 
autostarting, 166 
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Booting DOS (Cont) 
CTRL-K, CTRL-P Monitor boots, 167 
Integer BASIC, 167 
language System, 167 
Monitor jump booting, 166 

Branching 
BASIC statements, 81-84 
Monitor command, 247 

BRUN, 196, 265 

BSAVE, 195. 220, 266-67 
verifying, 247 


Calculator mode. See Immediate mode 
CALL, 106, 259, 266. See also USR 
Cards. See Circuit boards 
Carriage return, 94 
as part of string, 123 
Cassettes 
handling, 19 
reading memory from, 240-41 
reference tone, 240 
saving memory on, 239-40 
saving programs on, 47-49 
with sound, 227 
storing arrays on, 151-52 
write-protecting, 20 
Cassette recorder, 19. See a/so Cassettes 
adjusting playback volume, 20-21 
hookup, 4 
CATALOG, 26, 168, 169, 266 
CHAIN, 267 
Character set, changing printed, 149-50 
Checksum, 176, 240-41 
CHR$, 122-23, 150, 313 
Circuit boards 
Applesoft Firmware card, 7 
communications interface card, 7 
controller cards, 6, 7, 107-08 
Integer BASIC card, 7 
Language System card, 7, 14 
main, 2-3 
parallel printer interface card, 7 
serial interface card, 7 
CLEAR, 79, 267 
CLOSE, 178— 79, 183, 142, 268 
CLR, 79, 156, 268 
Color, 200 
complement, 222 
COLORz, 268 
Commas, 113-17, 142 
in data files, 183-85 
separating variables, 93 
Communications interface card, 7 
Compound program lines, 153 
Computed GOSUB, 91 
Computed GOTO, 82 
CON, 98, 156, 269 
Concatenation, 69 
Conditionals, 283 
Constants, 152-53 
CONT, 98, 269 
Control key. See CTRL 
COS, 314 
CTRL, 17-18 
CTRL-B, 15, 28, 49, 233 
CTRL-C, 30, 35, 46, 98, 192, 232, 233 
CTRL-E, 235, 238-39 
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CTRL-K, 167 
CTRL-P, 167, 248 
Monitor boot, 25 
CTRL-S, 46, 235 
CTRL-X, 18, 32, 56 
CTRL-Y, 249 
Cursor 
control, 119-20 
defined, 14 
determining horizontal position, 118 
determining vertical position, 119 
moving, 52-53 
positioning, 119—20 
special video effects, 119-27 
DATA, 59-61, 77, 156, 270 
Data entry, 108, 123-42 
allowing changes, 127-29 
backspacing, 141-42 
checking for errors, 129-31, 133, 135-36 
correcting errors, 141 
designing, 131-32 
forms, 136 
interactive, 124-27 
masks, 132, 136, 138, 141-42 
minimizing errors, 123 
operator aids, 141-42 
organization, 123 | 
range checking, 128-29 
style guidelines, 127 —29 
valid date, 131 
Data files. See Files 
Data window, 143-48 
Debugging programs, 154 
assembly language, 255-57 
DOS aids, 194-96 
Deferred mode. See Programmed mode 
DEF FN, 156, 270. See a/soFN 
DEL, 156, 271 
DELETE, 174-75, 180, 271 
DIM, 80, 272 
Direct mode. See Immediate mode 
Disassembled listings, 254-55 
Disk controller card, 7, 166 
Disk drive, 5, 157-67 
drive number, 170-71 
maximum number available, 171 
stot number, 170-71 
specifying in disk commands, 170-71 
Diskettes. See a/so Disk drives; Disks; DOS 
handling, 21 
hard sectored, 162 
index hole, 162 
inserting, 22 
Soft sectored, 162 
System Master Diskette, 21, 23, 25, 26, 28 
write protecting, 163 
Disk files. SeeFiles 
Disk Operating Systera. SeeDOS 
Disks. See a/soDiskettes 
binary image loading, 242—43 
blank, 172-74 
booting, 166-67 
buffer, 165 
catalog, 26 
crash, 165 
data storage process, 160 
deleting programs from, 174—75 
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directory, 165, 168 
floppy, 160 

hard, 156 

initializing, 27-28, 164, 172-74 
LOAD, 170 

mini-, 160 

RUN, 170 

shape tables, 220 
sectors, 160 

with sound, 226 

storage process, 165 
tracks, 160 

track/sector list, 164-65 
volume, 171-72 
Winchester, 158 


Disk 1, 5, 21, 157 
Display screen 


adjusting width, 52 

avoid last column, 146 

clearing, 119 

color adjustment, 30 

data window, 143-48 

design, 142 

determining screen color, 202 
dimensions of, 2 

80-column, 8, 14 

flashing video, 126 

formatting, 142 

full-screen graphics, 199 
high-resolution graphics, 203-10 
high-resolution shapes, 210-24 
hookup, 2 

low-resolution graphics, 197-203 
program listing, 46 

reverse video mode, 120, 248 
Soft switches, 341—42 

speed, 120 

television monitor, 1, 2 
television set, 1, 2 

text mode, 199 

wrap-around, 39, 147 


DOS 


booting, 22-26, 49, 166-67 
memory requirements, 350 


Mini-Assembler, 250 
Monitor commands, 238 
PEEK and POKE locations, 351 
ESC, 18, 53, 54, 56 
ESC-6, 32, 50 
Escape key. See ESC 
EXEC, 191-93, 274 
EXP, 314 
Expressions, 68 
arithemetic, 70, 71 
Boolean, 73 
тегі, 71 
relational, 71 


File pointer, 179-82 
moving, 186, 190 

Files 
buffers, 178, 193 
closing, 165 
deleting from disk, 174 
disk, 164 
END OF DATA, 183, 186 
EXEC, 191 
field positioning, 186, 190 
field separation, 185 
GET, 184 


Integer BASIC/Applesoft differences, 183 


locking, 168, 175 
machine language, 195 
names, 169, 181 
random access, 187-91 
renaming, 175 
sectors used, 169 
sequential, 177-83 
storing numbers in, 185 
types, 168 
unlocking, 175 
verifying, 176 

FN, 314. See also DEF FN 

FOR, 84, 85, 120, 156, 180, 275 

Formatting, 116 

FP, 28, 40, 276 

FRE, 154, 314 

Functions, 99-104 
nested, 104 


programmed mode, 107, 108, 148-49 
versions of, 26, 164—65, 167 
DRAW, 222, 273 
Drive number, 170-71 
DSP, 155, 273 
Editing, 18, 32 
adding lines, 51 
changing characters, 53 
changing lines, 51-55 


numeric, 100-01 
string, 102 

system, 103 
user-defined, 103-04 


Game controls, 9, 210, 354 


operating, 105 
PEEK and POKE locations, 343-44 
sensing, 105 


deleting characters, 53 
deleting lines, 50—51 

edit mode, 52—53 

erase to end of line, 54 
erase to end of screen, 54 
ESC sequence, 52-53 
inserting characters, 54 


Edit mode, 52-53 


Garbage collection, 354 

GET, 97, 133, 156, 277 
read text files, 184 

Ghost vectors, 211 

GOSUB, 89, 156, 277 
GOTO, 81-84, 278 

GR, 198, 279 

Graphics 


END, 43, 98, 156, 274 
Error message, 32, 40-41, 327-32 
Errors 
checking, input, 129-31 
correcting, 32 
correcting during data entry, 1-41 


low-resolution, 197-203 
full screen, 199 
high-resolution, 203-24 
text window, 199 


Graphics tablet, 10 
Greeting program, 27, 172, 176 


381 


382 


Hard disk crash, 165 
Hard disks, 157 
HCOLOR, 207, 279 
Hexadecimal! number 
arithmetic, 248-49 
conversion to decimal, 365-70 
HGR, 204-05, 280 
alternatives to, 205-06 
HGR2, 205, 280 
alternatives to, 205-06 
High-resolution graphics 
clearing high-resolution pages, 206-07 
colors, 207 
disk files with, 195-96 
drawing tines, 208-09 
Integer BASIC, 205-10 
memory requirements, 203-04 
pages, 203-04 
plotting points, 208-09 
reserving memory, 203-04 
restoring text mode, 206 
screen dimensions, 203 
setting up display, 204-07 
shapes, 210-24 
text window, 205 


HIMEM:, 106, 156, 204, 218, 221, 260, 281, 350, 


352 
HLIN, 201, 282 
HOME, 282 
HPLOT, 211, 282 
alternatives to, 209-10 
HTAB, 119, 142, 283 


IF-THEN, 91, 283 
Immediate mode, 38, 156, 261 
arithmetic, 39 
(№, 167, 285 
programmed mode, 107-08 
Index Register X, 236, 238-39 
Index Register Y, 236, 238-39 
Index variable, 84 
Indirect mode. See Programmed mode 
INIT, 172-74, 285 
INPUT, 94, 125-26, 132, 153, 156, 286 
checking for errors, 129-31 
disk files, 182 
EXEC files, 191 
mixed-type, 96 
INT, 29, 49, 287, 315 
Integer BASIC. See a/so BASIC; Programs 
accessing from Monitor, 232-33 
automatic line numbering, 47 
line numbers, 57 
memory usage, 350-52 
numeric values, 39 
restarting, 33-35 
Switching to Applesoft, 49-50 
tab stops in, 113 
variable names, 63 
Integer BASIC card, 7 
Integer expressions, 70 
Integer variables, 64 
Interface cards, 107 - 08 
Intrinsic subroutines, 333-37 
INVERSE, 120, 180, 287 


Job queuing, 191 
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Keyboard, 1, 16 
deactivating via Monitor, 248 


Language System, 23 
booting DOS, 25-26, 167 
card, 7, 14, 28 
LEFTS, 315 
Left-arrow key, 18-19, 32, 56 
LEN, 315 
LET, 76, 288 
Line length, 149-50 
adjusting printed, 149-50 
Lina numbers, 44, 57, 153 
as addresses, 58 
LIST, 45, 59, 288 
Listing. See Program listing 
LOAD, 29, 156, 289 
Loading programs. See Program loading 
LOCK, 175, 290 
Location counter, 251, 252—53, 254-55, 258 
LOG, 316 
Logical operators, 73 
LOMEM:, 106, 156, 204, 260, 290, 351-52 
Loops, 84-87, 275, 292 
nested, 85 - 87 
Lower-case letters, 16, 17 
Low-resolution graphics 
colors, 197-98, 200 
determining screen color, 202 
full-screen graphics, 199 
horizontal lines, 201 
pages, 197-99 
plotting points, 200 
Screen dimensions, 197 
text window, 199 
vertical lines, 201 


Machine Language Monitor. See Monitor 
Machine language programs, 250—60. See also 
Assembly language 
MAN, 47, 156, 291 
MAXFILES, 193-94, 291 
Memory 
address pointer, 234 
addressing, 105 
allocation, 260 
altering blocks, 237 
altering single addresses, 105, 236 
block moves, 196, 244 
capacity, 4 
comparing blocks, 245 
direct access via BASIC, 105 
examining blocks, 234 
examining single addresses, 105, 233 
examining words, 234 
filling with a pattern, 242-43, 244 
maps, 350-54 
random-access (RAM), 4 
read-only (ROM), 4 
read/write (RAM), 4 
retrieving via Monitor, 240-41 
saving via BASIC, 195-96, 242 
saving via Monitor, 239 
setting boundaries, 106, 107 
specifying in BASIC, 105-06 
verifying saved, 246 
MIDS, 316 
Mini-Assembter, 249-54 
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accessing, 250 
exiting, 251 
instruction formats, 251—52 
location counter, 251—55 
Monitor commands, 250 
sample session, 253-54 
Mistakes. SeeErrors 
Mixed-type expressions, 74 
MOD, 70 
MON, 194, 292 
Monitor, 15, 231-51, 254—59 
accessing, 231 
address pointer, 235-37, 247 
alter registers, 238-39 
Autostart Monitor, 23, 232 
built-in subroutines, 258—60, 333 
commands, 238 
defined, 6 
examine memory, 233, 236 
examine registers, 235 
exiting, 232 
fill memory procedure, 244 
GO command, 233, 247 
input device selection, 248 
list command, 254-55 
location counter, 254-55 
move memory, 243 
output device selection, 248 
read memory, 240-41 
reverse video, 248 
saving memory, 239 
with sound, 225 
standard Monitor, 231 
step command, 254—56, 258 
trace command, 256 
user-definable command, 249 
verify memory, 244-46 
verify saved memory procedure, 246-47 


NEW, 43, 156, 292 
NEXT, 84, 156, 292 
NO DSP, 155, 293 
NOMON, 194-95, 293 
NORMAL, 120, 294 
МО TRACE, 154, 294 
Null DOS command, 182 
Null string, 59 
Numbers, 60-62 
integers, 60 
real numbers, 60-61 
scientific notation, 61 
Numeric values, printing as strings, 146 
Numeric variables, 64 


ONERR GOTO, 156, 183, 294 
error handling routine, 130 
machine language fix for, 295 
negating, 130 

ON-GOSUB, 91, 295 

ON-GOTO, 83, 296 

OPEN 178, 187, 296. See a/so APPEND 

Operators 
arithmetic, 68 
Boolean, 68 
precedence of, 68 
relational, 68 
string, 68 


Output 
aligning numeric values, 146 
array, 143 
formatting, 142 


Paddles. See Game controls 
Parallel printer interface card, 7, 148 
Parentheses, 69 
PDL, 316 
PEEK, 106, 317 
determining cursor column, 118 
determining cursor row, 119 
useful locations, 339 
Peripheral devices 
input from, 107-08 
output from, 107-08 
PLOT, 200, 297 
in text mode, 297 
Plotting vectors, 211 
codes, 212 


assembling vectors by computer, 216 


POKE, 106, 260, 298 
with graphics, 199, 205-06 
with shapes, 219, 221 
text window, 121-22 
useful locations, 339 
POP, 90, 135, 298 
POS, 118, 317 
Power-on, 13 
PR*, 148, 150-51, 167, 299 
programmed mode, 107-08 
Precedence, 68-69 
overriding, 69 


PRINT statement, 93, 108, 154, 299 


abbreviated, 40 

commas іп, 113-15, 142 
disk files 179—82, 185 
DOS commands, 107-08 
formatting, 116—18 
numeric data, 111-15 
numerics as strings, 146 
semicolons in, 109-13 
SPC in, 117 

strings, 109-10, 114-15 
TAB in, 117 


Printer 
activating via Monitor, 2g 
CHR$ with, 150 
control codes, 150 
character set, 149-50 
formatting, 142 
hookup, 10 
line length, 149-50 
page size, 149-50 
programmable, 149-50 
selecting for output, 148 
Printing a heading, 116-17 
Printing program listings, 150—51 
Program Counter, 235, 238-39 
Program loading 
cassette, 29 
disk, 29-30 
Progam examples 
assembly language sound, 253 
blanket, 127 
display data entry form, 136-37 
display data window, 145—46 
end of file marker, 264 
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Progam examples (Cont) 
greeting program, 172 


high-resolution Integer BASIC sketch, 210 


low-resolution diagonal line, 200 

random tow-resolution linas, 202 

shape definition, 216-18 

sound generator, 228-29 

speaker driver, 227 

text window input, 122 

valid date entry, 133-35 
Programmed mode, 38, 43, 261 


DOS commands, 107-08, 148-49, 176-77 


restrictions, 156 
Programming languages, 56-57 
diatects, 57 
syntax, 57 
Program output, 108-23, 142-51 
Programs 
adding lines, 45, 51 
blank spaces in, 58-59 
changing lines, 51—55 
compact, 153 
debugging, 154—55 
deleting from disk, 174-75 
deleting lines, 50-51 
ending, 43 
execution, 43 
faster, 152—53 
line length, 39, 45 
tine numbers, 44 
locking, 175 
multiple statement line, 45, 153 
optimization, 152-54 
renaming, 175 
saving on cassette, 47—49 
sequence of lines, 44-45, 58 
~, Statements, 41 
unlocking, 175 
verifying, 176 
Programs, types of 
application, 5 
greeting, 27, 172 
intepreter, 5 
Monitor, 6 
operating system, 6 
Prompt character, 15 
Applesoft, 16 
Integer BASIC, 15 
Monitor, 15 
Prompt message, 96-97, 127-29 
Prompts, INPUT statement, 96 


Quotation marks, as part of string, 123 


RAM. SeeMemory 
Random-access files 
closing, 187 
field positioning, 190 
opening, 187 
read, 187 
record length, 187 
record number, 187 
write, 187 
Random-access memory. See Memory 
Random numbers, 317 
READ, 77. 182—84, 186-87, 190-91 
assignment statement, 301 
disk statement, 300 
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EXEC files, 191 
Read-only memory. See Memory 
Read/write memory. See Memory 
Real variables, 65 
RECALL, 151-52 
Recopy. SeeRight-arrow key 
Recursion, 90 
Registers, 259 
altering, 238—39 
examining, 235 
Relational expressions, 71 
Relational operators, 71 
REM, 76, 153, 302 
RENAME, 175--76, 303 
REPT, 19, 32, 50, 56 
Reserved words, 65-66 
tokens, 361 
RESET, 16, 17, 35, 98, 256 
accidental, 17, 33 
recovering from, 33 
RESTORE, 79, 303 
RESUME, 130, 156, 303 
RETURN, 156, 304 
Reverse video, 120, 248 
RF modulator, 2, 13 
RIGHTS, 317 
Right-arrow key, 18-19, 32, 52, 54-56 
RND, 317 
ROM. See Memory 
ROT, 233, 304 
Roundoff, 62 
RUN 
disk statement, 304 
general statement, 30, 125, 156, 305 


SAVE, 156, 174, 305 
SCALE, 222-23, 306 
Scientific notation, 61 
Scratch variables, 153 
SCRN, 202, 318 
Sectors, 160 
hard, 162 
locating, 162 
Semicolon, 109-13, 142 
in date files, 185 
separating variables, 94 
Serial interface card, 7, 148 
Sequential files 
APPEND, 186 
closing. 178 
opening, 178-79 
writing to, 179-84 
SGN, 319 
Shapes 
assembling shape table, 211 
assembling vectors by computer, 216 
drawing, 222 
end of shape definition, 213 
erasing, 222 
loading shape table, 221 
reserving memory for, 218 
rotating, 223 
saving shape table, 220 
size changes, 222 
Shape tables, 211 
byte coding, 212-14 
directory, 214 
end of shape definition, 213 
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entering, 218-20 
loading, 221 
pointer to, 221 
saving, 220 
size, 214 
zero plotting vector, 213 
SHIFT, 17 
SHLOAD, 220-21, 306 
SIN, 319 
Stot numbers, 3, 6, 7, 148, 170-71 
selecting 107—08 
specifying in disk commands, 170 
Soft switches, 205, 341—42 
Soft disk crash, 165 
Sound, 224-29 
with machine language, 225, 227 
SPC, 117, 319 
Speaker, 105, 224 
РЕЕК and POKE locations, 341 
Special video effects, 119—22 
SPEED, 120, 307 
SOR, 319 
Stack Pointer Register, 236, 238-39 
STOP, 99, 307 
STORE, 151-52, 307 
STR$, 320 
Strings 
comparisons, 72 
concatenation, 69 
null string. 59 
variables, 63, 64 
Subroutine examples 
ask yes or no question, 128 
clearing high-resolution graphics pages, 206 
data entry mask, 132 
display row and column headings, 146 
enter string data, 137 - 38 
error handling, 131 
get numeric input, 128 
get two character entry, 133 
high-resolution Integer BASIC plot, 209 
set high-resolution background color, 208 
Subroutines 
built-in, 333-37 
calling BASIC, 277, 295 
calling assembly language, 266, 321 
data entry, 127-29 
exit with GOTO, 135 
nested, 90 
System Master Diskette, 21, 23, 25-26, 28, 
163, 167 
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TAB 
PRINT function, 117, 320 
statement, 119, 142, 308 
Tab stop, 113-14 
TAN, 320 
Tape recorder. See Cassette recorder 
Testing programs. See Debugging programs 
TEXT, 308 
Text mode, plotting in. 297 
TEXT window, 121-22 
PEEK and POKE locations, 340-41 
Tokens, 361 
TRACE, 154, 308 
with DOS, 195 
Tracks, 160 
locating, 162 
Truncation, 75 
Truth table, 73 
TV screen, 1. See a/so Display screen 


UNLOCK, 175, 309 

Upper-case letters, 16-17 
User-defined functions, 103, 270 
USR, 260, 321 


VAL, 321 
Variables, 152-53 
assigning values, 124-26 
format in memory, 351 
integer, 64 
names, 62, 66 
numeric, 64 
real, 65 
Scratch, 153 
string, 63-64 
Vectors 
plotting. 211-14 
ghost, 211 
VERIFY, 176, 309 
Viewfinder technique, 144 
VLIN, 310 
Votume number, 171-73 
VTAB, 119, 142, 310 


WAIT, 310 

Wrap-around, 39, 147 

WRITE, 179-82, 186-87, 190-91, 311 
Write enable notch, 163 

Write protect notch, 163 


XDRAW, 222, 312 
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